diff --git a/.gitignore b/.gitignore index d773e96b8..a43269e2e 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ __pycache__/ /_tools/wbe-gen/architecture/ _tools/wbe-gen/jars/ VEEPortingGuide/images/~$ui_overview2.pptx +.DS_Store diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 000000000..c67e7e392 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,17 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Build", + "type": "shell", + "command": "make html", + "problemMatcher": [], + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} diff --git a/ApplicationDeveloperGuide/UI/MWT/concepts.rst b/ApplicationDeveloperGuide/UI/MWT/concepts.rst index 811538bf5..ec03039b6 100644 --- a/ApplicationDeveloperGuide/UI/MWT/concepts.rst +++ b/ApplicationDeveloperGuide/UI/MWT/concepts.rst @@ -66,20 +66,84 @@ The render policy can be changed by overridding `Desktop.createRenderPolicy()`_. .. _section_layout_process: +Widget Lifecycle +---------------- + +Desktops and widgets run through different states. +Once created, they can be attached, then they can be laid out, and finally they can be shown. + +A desktop is attached automatically as soon as it is shown on the display and detached when hidden. +It can also be attached manually by calling `Desktop.setAttached()`_ or detached by calling `Desktop.setDetached()`_. +It is particularly useful to render the desktop (and its widgets) in a buffered image for example. + +A widget is considered as attached when it is contained in a desktop that is attached. +In the same way, by default, a widget is shown when its desktop is shown. +But for optimization purposes, a container can control when its children are shown or hidden. +A typical use case is when the widgets are moved outside the display (in a scroll container for instance). + +.. _Desktop.setAttached(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Desktop.html#setAttached-- +.. _Desktop.setDetached(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Desktop.html#setDetached-- + +Hooks +~~~~~ + +When attached, a widget is notified by a call to its `onAttached()`_ method. +This notification can be useful to allocate some images or other resources for example. +These resources can be used to compute the size of the widget and to render it. +In other words, after this call, a widget is ready to be laid out. + +After being laid out, a widget is notified by a call to its `onLaidOut()`_ method. +Being laid out means that its bounds inside its parent are set. +During this call, the widget can prepare some resources used later by the rendering. +For example, it can split a string into several lines based on its width. +Another idea could be to allocate a buffered image and draw the background to avoid repainting everything during the rendering. + +Beware that a widget can be laid out several times once attached (typically each time a `Desktop.requestLayOut()`_ or `Widget.requestLayOut()`_ is done). + +When a whole hierarchy is ready to be rendered, all the widgets are notified by a call to their `onShown()`_ method. +This notification is particularly useful to start a periodic refresh or an animation. + +A widget can finally be hidden and detached, in which cases its methods `onHidden()`_ and `onDetached()`_ will be called respectively. +In these methods, anything that has been started or allocated during the previous phases must be stopped or freed correctly to avoid memory leaks. + +.. _onAttached(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#onAttached-- +.. _onLaidOut(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#onLaidOut-- +.. _onShown(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#onShown-- +.. _onHidden(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#onHidden-- +.. _onDetached(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#onDetached-- + Lay Out -------- +~~~~~~~ -All widgets are laid out at once during the lay out process. This process can be started by `Desktop.requestLayOut()`_, `Widget.requestLayOut()`_. The layout is also automatically done when the desktop is shown (`Desktop.onShown()`_). This process is composed of two steps, each step browses the hierarchy of widgets following a depth-first algorithm: +All widgets are laid out at once during the lay out process. +This process can be started by `Desktop.requestLayOut()`_ or `Widget.requestLayOut()`_. +The layout is also automatically done when the desktop is shown (`Desktop.onShown()`_). -- compute the optimal size for each widget and container (considering the constraints of the lay out), -- set position and size for each widget. +This process is composed of two steps. +Each step browses the hierarchy of widgets following a depth-first algorithm: -Once the position and size of a widget is set, the widget is notified by a call to `onLaidOut()`_. +- Compute the optimal size for each widget and container (considering the constraints of the lay out). +- Set the position and size for each widget. + +A widget must implement its `Widget.computeContentOptimalSize()`_ method. +It is explained in detail in this section: :ref:`mwt_widget_optimalsize`. + +A container is responsible for laying out its children. +For that it must implement its own `Widget.computeContentOptimalSize()`_ method and call the `Container.computeChildOptimalSize()`_ method for each of its children. +And it must implement its `Container.layOutChildren()`_ method and call the `Container.layOutChild()`_ method for each of its children. +It is explained in detail in these sections: :ref:`mwt_container_optimalsize` and :ref:`mwt_container_layout`. .. _Desktop.requestLayOut(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Desktop.html#requestLayOut-- .. _Widget.requestLayOut(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#requestLayOut-- .. _Desktop.onShown(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Desktop.html#onShown-- -.. _onLaidOut(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#onLaidOut-- +.. _Widget.computeContentOptimalSize(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#computeContentOptimalSize-ej.mwt.util.Size- +.. _Container.computeChildOptimalSize(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Container.html#computeChildOptimalSize-ej.mwt.Widget-int-int- +.. _Container.layOutChildren(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Container.html#layOutChildren-int-int- +.. _Container.layOutChild(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Container.html#layOutChild-ej.mwt.Widget-int-int-int-int- + +.. figure:: images/widgetLifecycle.png + :alt: Desktop and Widget Lifecycle + :align: center .. _rendering_pipeline: @@ -222,7 +286,7 @@ Font The font is not used by framework itself, but it may be used in the ``renderContent()`` to select the font to use when drawing strings. -Extra fields +Extra Fields ~~~~~~~~~~~~ Extra fields are not used by framework itself, but they may be used in the ``renderContent()`` to customize the behavior and the appearance of the widget. @@ -255,6 +319,30 @@ For example, the following code customizes the style of every `Label`_ widget of .. _CascadingStylesheet: https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/stylesheet/cascading/CascadingStylesheet.html .. _Label: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/basic/Label.html +Widget's Style +-------------- + +At any time, a widget has a style that can be retrieved using `Widget.getStyle()`_ method. + +When created, the widget's style contains the default value for each field. +These default values are defined in the `DefaultStyle`_ class. + +Once it is attached to a desktop, the widget's style is computed from the stylesheet set in the desktop. +This is done using the `Stylesheet.getStyle()`_ method. +The style can then be used when laying out and rendering the widget. + +At any time, the style of the widget can be recomputed by calling `Widget.updateStyle()`_. +For example when its state changes: + +- When a button is pressed or released. +- When a checkbox is checked or unchecked. +- etc. + +.. _Widget.getStyle(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#getStyle-- +.. _DefaultStyle: https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/style/DefaultStyle.html +.. _Stylesheet.getStyle(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/stylesheet/Stylesheet.html#getStyle-ej.mwt.Widget- +.. _Widget.updateStyle(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#updateStyle-- + .. _section_animations: Animations @@ -267,7 +355,7 @@ See chapter :ref:`section_animate_widget` for more information on animating a wi .. _Animator: https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/animation/Animator.html -Partial buffer considerations +Partial Buffer Considerations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Rendering a widget in :ref:`partial buffer mode ` may require multiple cycles if the buffer is not big enough to hold all the pixels to update in a single shot. @@ -280,30 +368,6 @@ For example, a transition on a small part of the screen will look better than a A transition will look perfect if the partial buffer can hold all the lines to repaint. Since the buffer holds a group of lines, a horizontal transition may not look the same as a vertical transition. -Desktop and widget states -------------------------- - -Desktop and widgets pass through different states. Once created, they can be attached, then they can be shown. - -A desktop is attached automatically as soon as it is shown on the display. -It can also be attached manually by calling `Desktop.setAttached()`_. It could be used to render the desktop (and its widgets) on an image for example. - -A widget is considered as attached when it is contained by a desktop that is attached. - -In the same way, by default, a widget is shown when its desktop is shown. But for optimization purpose, a container can control when its children are shown or hidden. A typical use case is when the widgets are moved outside the display. - -Once a widget is attached, it means that it is ready to be shown (for instance, the necessary resources are allocated). In other words, once attached a widget is ready to be rendered (on an image or on the display). - -Once a widget is shown, it means that it is intended to be rendered on the display. While shown, it may start a periodic refresh or an animation. - -.. figure:: images/showSequence.png - :alt: Show Sequence - :align: center - -The following sections will present several ways to customize and extend the framework to better fit your needs. - -.. _Desktop.setAttached(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Desktop.html#setAttached-- - .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/ApplicationDeveloperGuide/UI/MWT/how-to-container.rst b/ApplicationDeveloperGuide/UI/MWT/how-to-container.rst index 7e18bab48..5b59bfebb 100644 --- a/ApplicationDeveloperGuide/UI/MWT/how-to-container.rst +++ b/ApplicationDeveloperGuide/UI/MWT/how-to-container.rst @@ -7,12 +7,14 @@ Container subclasses have to implement two methods and may override optional met .. _Container: https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Container.html -Implementing the mandatory methods +Implementing the Mandatory Methods ---------------------------------- This section explains how to implement the two mandatory methods of a container subclass. -Computing the optimal size of the container +.. _mwt_container_optimalsize: + +Computing the Optimal Size of the Container ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `computeContentOptimalSize()`_ method is called by the MWT framework in order to know the optimal size of the container. @@ -42,7 +44,9 @@ For example, the following snippet computes the optimal size of a simple wrapper .. _getHeight(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#getHeight-- .. _Widget.NO_CONSTRAINT: https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#NO_CONSTRAINT -Laying out the children of the container +.. _mwt_container_layout: + +Laying out the Children of the Container ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `layOutChildren()`_ method is called by the MWT framework in order to lay out every child of the container, i.e. to set the position and size of the children. @@ -67,7 +71,7 @@ For example, the following snippet lays out the children of a simple wrapper: .. _layOutChildren(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Container.html#layOutChildren-int-int- .. _layOutChild(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Container.html#layOutChild-ej.mwt.Widget-int-int-int-int- -Managing the visibility of the children of the container +Managing the Visibility of the Children of the Container -------------------------------------------------------- By default, when a container is shown, each of its children is shown too. @@ -83,7 +87,7 @@ When a container is hidden, each of its children is hidden too (unless it is alr .. _setHiddenChild(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Container.html#setHiddenChild-ej.mwt.Widget- .. _setHiddenChildren(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Container.html#setHiddenChildren-- -Providing APIs to change the children list of the container +Providing APIs to Change the Children list of the Container ----------------------------------------------------------- The `Container`_ class introduces ``protected`` APIs in order to manipulate the list of children of the container. diff --git a/ApplicationDeveloperGuide/UI/MWT/how-to-debug.rst b/ApplicationDeveloperGuide/UI/MWT/how-to-debug.rst index 4a3068cf8..c449d3ce0 100644 --- a/ApplicationDeveloperGuide/UI/MWT/how-to-debug.rst +++ b/ApplicationDeveloperGuide/UI/MWT/how-to-debug.rst @@ -127,6 +127,219 @@ Here is an example of a ``xxx.constants.list`` file with the result in an applic .. note:: Available since MWT 3.5.0 & Widget 5.0.0. +Detecting Text Overflow +----------------------- + + +Widgets that display a text may experience text overflow when the strings are too long to fit into the available area. +It can be the case, for example, in applications that support multiple languages because widgets have to deal with texts of different lengths. + +This document presents a solution to detect such text overflows. + + +Instrumenting the Widget +~~~~~~~~~~~~~~~~~~~~~~~~ + +The goal is to check whether the text to be displayed is within the content bounds of the widget. A way to test this is to extend or modify the widget. +In this article, the widget ``MyLabel`` will extend the type `Label`_ from the Widget library, which displays a text: + +.. code-block:: java + :emphasize-lines: 3 + + import ej.widget.basic.Label; + + public class MyLabel extends Label { + + public MyLabel(String text) { + super(text); + } + } + + +.. _Label: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/basic/Label.html + +Overriding the onLaidOut() Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the position and size of a wigdet are set during the lay out process, the `onLaidOut()`_ method is called to notify the widget. +Overriding `onLaidOut()`_ of class ``MyLabel`` is a good place to check whether the text overflows or not. + +For example, the following snippet compares the text width with the available width: it will print a message if an overflow is detected. + +.. code-block:: java + :emphasize-lines: 12,13,14 + + @Override + protected void onLaidOut() { + super.onLaidOut(); + + // compute the width of the text with the specified font + final Font font = getStyle().getFont(); + final String text = getText(); + final int textWidth = font.stringWidth(text); + + // compare to the width available for the content of the widget + final int contentWidth = getContentBounds().getWidth(); + if (textWidth > contentWidth) { + System.out.println("Overflow detected:\n > Text: \"" + text + "\"\n > Width = " + textWidth + " px (available: " + contentWidth + " px)"); + } + } + +.. _onLaidOut(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#onLaidOut-- + +Testing +~~~~~~~ + +Here is a case where the widget size is set manually to be a little shorter than the text width: + +.. code-block:: java + :emphasize-lines: 6 + + public static void main(String[] args) { + MicroUI.start(); + Desktop desktop = new Desktop(); + Canvas canvas = new Canvas(); + // add a label with an arbitrary fixed width of 25 pixels (which is too short) + canvas.addChild(new MyLabel("Some text"), 20, 20, 25, 10); + desktop.setWidget(canvas); + desktop.requestShow(); + } + +.. image:: images/tuto_microej_bounds_check.png + :alt: Text overflow example + :align: center + +The text is cropped and the console logs that a text overflow has been detected: + +.. code-block:: console + + =============== [ Initialization Stage ] =============== + =============== [ Converting fonts ] =============== + =============== [ Converting images ] =============== + =============== [ Launching on Simulator ] =============== + Overflow detected: + > Text: "Some text" + > Width = 47 px (available: 25 px) + + +Improving the Detection +~~~~~~~~~~~~~~~~~~~~~~~ + +To ease the correction process, it is best to add some additional debug information to locate the issue. +Let's extract the text overflow detection into a helper class, so that it is available for all classes across the application. + +The following snippet: + +* extracts the text overflow detection into the class ``MyTextHelper``. +* prints the part of the text that is displayed. +* prints the path to the widget in the widget tree to help the tester locate the affected widget in the GUI. + +.. code-block:: java + :emphasize-lines: 13,30 + + public class MyLabel extends Label { + + public MyLabel(String text) { + super(text); + } + + @Override + protected void onLaidOut() { + super.onLaidOut(); + + final Font font = getStyle().getFont(); + final String text = getText(); + MyTextHelper.checkTextOverflow(this, text, font); + } + } + + public class MyTextHelper { + + /** + * Checks whether the given text overflows for the specified widget and font. In the case where an overflow is + * detected, the method prints a message that details the error. + * + * @param widget + * the widget that displays the text. + * @param text + * the text to display. + * @param font + * the font used for drawing the text. + */ + public static void checkTextOverflow(final Widget widget, final String text, final Font font) { + final int textWidth = font.stringWidth(text); + final int contentWidth = widget.getContentBounds().getWidth(); + + if (textWidth > contentWidth) { + String displayedText = buildDisplayedText(text, font, contentWidth); + String widgetPath = buildWidgetPath(widget); + System.out.println( + "Overflow detected:\n > Text: \"" + text + "\"\n > Width = " + textWidth + " px (available: " + + contentWidth + " px) \n > Displayed: \"" + displayedText + "\"\n > Path : " + widgetPath); + } + } + + private static String buildDisplayedText(String text, Font font, int width) { + for (int i = text.length() - 1; i > 0; i--) { + if (font.substringWidth(text, 0, i) <= width) { + return text.substring(0, i); + } + } + + return ""; + } + + private static String buildWidgetPath(Widget widget) { + StringBuilder builder = new StringBuilder(); + + Widget ancestor = widget; + do { + builder.insert(0, " > " + ancestor.getClass().getSimpleName()); + ancestor = ancestor.getParent(); + } while (ancestor != null); + builder.insert(0, widget.getDesktop().getClass().getSimpleName()); + + return builder.toString(); + } + } + +When the application is launched again, the console shows more information about the text overflow: + +.. code-block:: console + + =============== [ Initialization Stage ] =============== + =============== [ Converting fonts ] =============== + =============== [ Converting images ] =============== + =============== [ Launching on Simulator ] =============== + Overflow detected: + > Text: "Some text" + > Width = 47 px (available: 25 px) + > Displayed: "Some" + > Path : Desktop > Canvas > MyLabel + + +To keep control over the extra verbosity and code size, one option is to use :ref:`BON constants ` to enable/disable this debug code at will. +In the following snippet, when the constant ``com.mycompany.check.text.overflow`` is set to ``false``, the debug code will not be embedded in the application. + +.. code-block:: java + :emphasize-lines: 2 + + public static void checkTextOverflow(final Widget widget, final String text, final Font font) { + if (Constants.getBoolean("com.mycompany.check.text.overflow")) { + final int textWidth = font.stringWidth(text); + final int contentWidth = widget.getContentBounds().getWidth(); + + if (textWidth > contentWidth) { + String displayedText = buildDisplayedText(text, font, contentWidth); + String widgetPath = buildWidgetPath(widget); + System.out.println( + "Overflow detected:\n > Text: \"" + text + "\"\n > Width = " + textWidth + " px (available: " + + contentWidth + " px) \n > Displayed: \"" + displayedText + "\"\n > Path : " + widgetPath); + } + } + } + + .. | Copyright 2021-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/ApplicationDeveloperGuide/UI/MWT/how-to-widget.rst b/ApplicationDeveloperGuide/UI/MWT/how-to-widget.rst index 1da029d71..4d6cb28b9 100644 --- a/ApplicationDeveloperGuide/UI/MWT/how-to-widget.rst +++ b/ApplicationDeveloperGuide/UI/MWT/how-to-widget.rst @@ -10,10 +10,12 @@ Widget subclasses have to implement two methods and may override optional method .. _Widget: https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html -Implementing the mandatory methods +Implementing the Mandatory Methods ---------------------------------- -Computing the optimal size of the widget +.. _mwt_widget_optimalsize: + +Computing the Optimal Size of the Widget ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `computeContentOptimalSize()`_ method is called by the MWT framework in order to know the optimal size of the widget. @@ -41,7 +43,7 @@ For example, the following snippet computes the optimal size of an image widget: .. _Widget.NO_CONSTRAINT: https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#NO_CONSTRAINT .. _getStyle(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#getStyle-- -Rendering the content of the widget +Rendering the Content of the Widget ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `renderContent()`_ method is called by the MWT framework in order to render the content of the widget. @@ -68,7 +70,7 @@ For example, the following snippet renders the content of an image widget: .. _renderContent(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#renderContent-ej.microui.display.GraphicsContext-int-int- -Handling events +Handling Events --------------- When a widget is created, it is disabled and it will not receive any event. @@ -90,7 +92,7 @@ For example, the following snippet prints a message when the widget receives an .. _setEnabled(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#setEnabled-boolean- .. _handleEvent(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#handleEvent-int- -Consuming events +Consuming Events ~~~~~~~~~~~~~~~~ To indicate that an event was consumed by a widget, `handleEvent()`_ should return ``true``. @@ -111,7 +113,7 @@ The following guidelines are recommended to decide when to consume an event and .. _Pointer.PRESSED: https://repository.microej.com/javadoc/microej_5.x/apis/ej/microui/event/generator/Buttons.html#PRESSED -Listening to the life-cycle hooks +Listening to the Life-cycle Hooks --------------------------------- `Widget`_ subclasses may override the following methods in order to allocate and free the necessary resources: @@ -122,7 +124,7 @@ Listening to the life-cycle hooks - `onShown() `_ - `onHidden() `_ -For example, the ``onAttached()`` method may be overridden to load an image: +The ``onAttached()`` method may be overridden to load an image: .. code-block:: Java @@ -140,7 +142,18 @@ Likewise, the ``onDetached()`` method may be overridden to close the image: this.image.close(); } -For example, the ``onShown()`` method may be overridden to start an animation: +The ``onLaidOut()`` method may be overridden to split a String into several lines based on the widget's width: + +.. code-block:: Java + + @Override + protected void onLaidOut() { + Style style = getStyle(); + Font font = style.getFont(); + this.splittedText = TextHelper.wrap(getText(), font, getContentBounds().getWidth()); + } + +The ``onShown()`` method may be overridden to start an animation: .. code-block:: Java diff --git a/ApplicationDeveloperGuide/UI/MWT/images/showSequence.png b/ApplicationDeveloperGuide/UI/MWT/images/showSequence.png deleted file mode 100644 index 1cfdb7250..000000000 Binary files a/ApplicationDeveloperGuide/UI/MWT/images/showSequence.png and /dev/null differ diff --git a/Tutorials/images/tuto_microej_bounds_check.png b/ApplicationDeveloperGuide/UI/MWT/images/tuto_microej_bounds_check.png similarity index 100% rename from Tutorials/images/tuto_microej_bounds_check.png rename to ApplicationDeveloperGuide/UI/MWT/images/tuto_microej_bounds_check.png diff --git a/ApplicationDeveloperGuide/UI/MWT/images/widgetLifecycle.png b/ApplicationDeveloperGuide/UI/MWT/images/widgetLifecycle.png new file mode 100644 index 000000000..a4e77ef42 Binary files /dev/null and b/ApplicationDeveloperGuide/UI/MWT/images/widgetLifecycle.png differ diff --git a/ApplicationDeveloperGuide/UI/MicroUI/traces.rst b/ApplicationDeveloperGuide/UI/MicroUI/traces.rst index 0f2947abc..53a45f5e1 100644 --- a/ApplicationDeveloperGuide/UI/MicroUI/traces.rst +++ b/ApplicationDeveloperGuide/UI/MicroUI/traces.rst @@ -3,7 +3,7 @@ Debug Traces ============= -MicroUI logs several actions when traces are enabled. +MicroUI logs several actions when traces are enabled (see :ref:`event-tracing`). This chapter explains the trace identifiers. .. note:: Most of the logs are only available on the Embedded VEE Port (not on the Simulator). diff --git a/Tutorials/tutorialAppendEmojisToVectorFont.rst b/ApplicationDeveloperGuide/UI/MicroVG/how-to-add-emoji-to-vector-font.rst similarity index 91% rename from Tutorials/tutorialAppendEmojisToVectorFont.rst rename to ApplicationDeveloperGuide/UI/MicroVG/how-to-add-emoji-to-vector-font.rst index 088cd2eda..7ea3e791b 100644 --- a/Tutorials/tutorialAppendEmojisToVectorFont.rst +++ b/ApplicationDeveloperGuide/UI/MicroVG/how-to-add-emoji-to-vector-font.rst @@ -1,4 +1,4 @@ -.. _tutorial_append_emojis: +.. _how_to_add_emoji_to_vector_font: How to Add Emojis to a Vector Font ================================== @@ -18,16 +18,6 @@ This article shows how to achieve this using FontLab, a third-party font editor. (e.g. `FontTools `_, `FontForge `_ which are great tools for font editing). -Intended Audience ------------------ - -The audience for this document is Application engineers who want to -use :ref:`section_vector_fonts` in their applications. - -In addition, this tutorial should be of interest to all developers -wishing to familiarize themselves with the vector features of :ref:`MicroVG `. - - Prerequisites ------------- diff --git a/Tutorials/images/emojisAppend.png b/ApplicationDeveloperGuide/UI/MicroVG/images/emojisAppend.png similarity index 100% rename from Tutorials/images/emojisAppend.png rename to ApplicationDeveloperGuide/UI/MicroVG/images/emojisAppend.png diff --git a/Tutorials/images/emojisCopy.png b/ApplicationDeveloperGuide/UI/MicroVG/images/emojisCopy.png similarity index 100% rename from Tutorials/images/emojisCopy.png rename to ApplicationDeveloperGuide/UI/MicroVG/images/emojisCopy.png diff --git a/Tutorials/images/emojisExport.png b/ApplicationDeveloperGuide/UI/MicroVG/images/emojisExport.png similarity index 100% rename from Tutorials/images/emojisExport.png rename to ApplicationDeveloperGuide/UI/MicroVG/images/emojisExport.png diff --git a/Tutorials/images/emojisProfiles.png b/ApplicationDeveloperGuide/UI/MicroVG/images/emojisProfiles.png similarity index 100% rename from Tutorials/images/emojisProfiles.png rename to ApplicationDeveloperGuide/UI/MicroVG/images/emojisProfiles.png diff --git a/ApplicationDeveloperGuide/UI/MicroVG/index.rst b/ApplicationDeveloperGuide/UI/MicroVG/index.rst index b1cb623ac..f6fa5dcaa 100644 --- a/ApplicationDeveloperGuide/UI/MicroVG/index.rst +++ b/ApplicationDeveloperGuide/UI/MicroVG/index.rst @@ -16,6 +16,7 @@ MicroVG Foundation Library provides vector drawing capabilities. vectorimage traces avdLoader + how-to-add-emoji-to-vector-font .. diff --git a/ApplicationDeveloperGuide/UI/MicroVG/path.rst b/ApplicationDeveloperGuide/UI/MicroVG/path.rst index 552c261bd..75e846646 100644 --- a/ApplicationDeveloperGuide/UI/MicroVG/path.rst +++ b/ApplicationDeveloperGuide/UI/MicroVG/path.rst @@ -1,7 +1,7 @@ .. include:: aliases.rst Path -============ +==== .. _Path creation: diff --git a/ApplicationDeveloperGuide/UI/MicroVG/traces.rst b/ApplicationDeveloperGuide/UI/MicroVG/traces.rst index 77138d35d..2255de2a1 100644 --- a/ApplicationDeveloperGuide/UI/MicroVG/traces.rst +++ b/ApplicationDeveloperGuide/UI/MicroVG/traces.rst @@ -125,8 +125,6 @@ The following text can be copied in a file called ``SYSVIEW_MicroVG.txt`` and co NamedType VGDraw 4=DRAW_STRING_ON_CIRCLE NamedType VGDraw 5=DRAW_STRING_ON_CIRCLE_GRADIENT NamedType VGDraw 6=DRAW_IMAGE - NamedType VGDraw 7=DRAW_VGLITE_PATH - NamedType VGDraw 8=UPLOAD_VGLITE_PATH 0 VG_ImageEvent (MicroVG) Execute image event %VGImage | (MicroVG) Image event %VGImage done 1 VG_FontEvent (MicroVG) Execute font event %VGFont | (MicroVG) Font event %VGFont done diff --git a/ApplicationDeveloperGuide/UI/MicroVG/usage.rst b/ApplicationDeveloperGuide/UI/MicroVG/usage.rst index 3eae18923..b528b09fc 100644 --- a/ApplicationDeveloperGuide/UI/MicroVG/usage.rst +++ b/ApplicationDeveloperGuide/UI/MicroVG/usage.rst @@ -11,13 +11,13 @@ To use the MicroVG Foundation Library, add `MicroVG API module`_ to the project .. code-block:: java - implementation("ej.api:microvg:1.2.0") + implementation("ej.api:microvg:1.6.0") .. tab:: MMM (module.ivy) .. code-block:: xml - + The MicroVG Library brings the following features: diff --git a/ApplicationDeveloperGuide/UI/MicroVG/vectorfont.rst b/ApplicationDeveloperGuide/UI/MicroVG/vectorfont.rst index 64cadaad3..16d64676d 100644 --- a/ApplicationDeveloperGuide/UI/MicroVG/vectorfont.rst +++ b/ApplicationDeveloperGuide/UI/MicroVG/vectorfont.rst @@ -189,7 +189,7 @@ Only font files with CPAL/COLR tables are supported. Font files with CBDT/CBLC tables are not supported. -To add colored emojis to a font, see the tutorial :ref:`tutorial_append_emojis`. +To add colored emojis to a font, see the tutorial :ref:`how_to_add_emoji_to_vector_font`. .. _metrics_and_text_positioning: diff --git a/ApplicationDeveloperGuide/UI/MicroVG/vectorimage.rst b/ApplicationDeveloperGuide/UI/MicroVG/vectorimage.rst index 047f94ccb..32a6210d6 100644 --- a/ApplicationDeveloperGuide/UI/MicroVG/vectorimage.rst +++ b/ApplicationDeveloperGuide/UI/MicroVG/vectorimage.rst @@ -14,10 +14,13 @@ Images that must be processed by the image generator tool are declared in ``*.ve Currently accepted formats are : -- ``:VGF``: vglite compatible format with coordinates encoded as float numbers (32 bits). -- ``:VG32``: vglite compatible format with coordinates encoded as signed int numbers (32 bits). -- ``:VG16``: vglite compatible format with coordinates encoded as signed short numbers (16 bits). -- ``:VG8``: vglite compatible format with coordinates encoded as signed char numbers (8 bits). +- ``:VGF``: MicroVG compatible format with coordinates encoded as float numbers (32 bits). +- ``:VG32``: MicroVG compatible format with coordinates encoded as signed int numbers (32 bits). +- ``:VG16``: MicroVG compatible format with coordinates encoded as signed short numbers (16 bits). +- ``:VG8``: MicroVG compatible format with coordinates encoded as signed char numbers (8 bits). + +.. note:: The ouput format may be adjusted by the MicroVG engine to fit the capabilities of the vectorial GPU. + Example: diff --git a/ApplicationDeveloperGuide/UI/Motion/concepts.rst b/ApplicationDeveloperGuide/UI/Motion/concepts.rst new file mode 100644 index 000000000..e23ad0d4c --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/concepts.rst @@ -0,0 +1,313 @@ +.. _motion_concepts: + +Concepts +======== + +Functions +--------- + +The `Function`_ interface represents a mathematical function. +Its purpose is to associate a floating value to any input floating value between ``0f`` and ``1f``. +This function specifies the rate of change of a parameter over time (for example the position of an object). + +The library provides a set of functions among the most common ones. +Each one contains a convenient instance. +For example the `singleton for the linear function`_. + +Simple functions +~~~~~~~~~~~~~~~~ + +The `constant function`_ represents a constant motion whose value is always the stop value. + +.. image:: images/constant.svg + :width: 150px + +The `linear function`_ represents a uniform linear motion: the velocity is constant (no acceleration or deceleration). + +.. image:: images/linear.svg + :width: 150px + +Easing functions +~~~~~~~~~~~~~~~~ + +The easing functions come in 3 forms: + +- Ease-in: the function is eased at the beginning. +- Ease-out: the function is eased at the end. +- Ease-in-out: the function is eased at the beginning and the end. + +Here are the easing functions available in the library: + +|startTable| +`Circ ease-in`_ + +.. image:: images/circ-ease-in.svg + :width: 150px + +|secondColumn| +`Circ ease-out`_ + +.. image:: images/circ-ease-out.svg + :width: 150px + +|thirdColumn| +`Circ ease-in-out`_ + +.. image:: images/circ-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Cubic ease-in`_ + +.. image:: images/cubic-ease-in.svg + :width: 150px + +|secondColumn| +`Cubic ease-out`_ + +.. image:: images/cubic-ease-out.svg + :width: 150px + +|thirdColumn| +`Cubic ease-in-out`_ + +.. image:: images/cubic-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Expo ease-in`_ + +.. image:: images/expo-ease-in.svg + :width: 150px + +|secondColumn| +`Expo ease-out`_ + +.. image:: images/expo-ease-out.svg + :width: 150px + +|thirdColumn| +`Expo ease-in-out`_ + +.. image:: images/expo-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Quad ease-in`_ + +.. image:: images/quad-ease-in.svg + :width: 150px + +|secondColumn| +`Quad ease-out`_ + +.. image:: images/quad-ease-out.svg + :width: 150px + +|thirdColumn| +`Quad ease-in-out`_ + +.. image:: images/quad-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Quart ease-in`_ + +.. image:: images/quart-ease-in.svg + :width: 150px + +|secondColumn| +`Quart ease-out`_ + +.. image:: images/quart-ease-out.svg + :width: 150px + +|thirdColumn| +`Quart ease-in-out`_ + +.. image:: images/quart-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Quint ease-in`_ + +.. image:: images/quint-ease-in.svg + :width: 150px + +|secondColumn| +`Quint ease-out`_ + +.. image:: images/quint-ease-out.svg + :width: 150px + +|thirdColumn| +`Quint ease-in-out`_ + +.. image:: images/quint-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Sine ease-in`_ + +.. image:: images/sine-ease-in.svg + :width: 150px + +|secondColumn| +`Sine ease-out`_ + +.. image:: images/sine-ease-out.svg + :width: 150px + +|thirdColumn| +`Sine ease-in-out`_ + +.. image:: images/sine-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Back ease-in`_ + +.. image:: images/back-ease-in.svg + :width: 150px + +|secondColumn| +`Back ease-out`_ + +.. image:: images/back-ease-out.svg + :width: 150px + +|thirdColumn| +`Back ease-in-out`_ + +.. image:: images/back-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Bounce ease-in`_ + +.. image:: images/bounce-ease-in.svg + :width: 150px + +|secondColumn| +`Bounce ease-out`_ + +.. image:: images/bounce-ease-out.svg + :width: 150px + +|thirdColumn| +`Bounce ease-in-out`_ + +.. image:: images/bounce-ease-in-out.svg + :width: 150px + +|endTable| + +|startTable| +`Elastic ease-in`_ + +.. image:: images/elastic-ease-in.svg + :width: 150px + +|secondColumn| +`Elastic ease-out`_ + +.. image:: images/elastic-ease-out.svg + :width: 150px + +|thirdColumn| +`Elastic ease-in-out`_ + +.. image:: images/elastic-ease-in-out.svg + :width: 150px + +|endTable| + +Custom Function +~~~~~~~~~~~~~~~ + +It is possible to create custom functions by creating a class implementing the `Function`_ interface. +The `computeValue(float)` method should return a value between ``0f`` and ``1f``. + +Motion +------ + +The `Motion`_ class is used to describe the movement of an element. +It is made of a function, a start value, a stop value and a duration. + +It proposes a convenient method `Motion.getValue(long)`_ to retrieve the position of the element at the specified elapsed time. + + +.. _Function: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/Function.html +.. _linear function: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/linear/LinearFunction.html +.. _constant function: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/constant/ConstantFunction.html +.. _singleton for the linear function: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/linear/LinearFunction.html#INSTANCE +.. _Cubic ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/cubic/CubicEaseInFunction.html +.. _Cubic ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/cubic/CubicEaseOutFunction.html +.. _Cubic ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/cubic/CubicEaseInOutFunction.html +.. _Circ ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/circ/CircEaseInFunction.html +.. _Circ ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/circ/CircEaseOutFunction.html +.. _Circ ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/circ/CircEaseInOutFunction.html +.. _Expo ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/expo/ExpoEaseInFunction.html +.. _Expo ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/expo/ExpoEaseOutFunction.html +.. _Expo ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/expo/ExpoEaseInOutFunction.html +.. _Quad ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quad/QuadEaseInFunction.html +.. _Quad ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quad/QuadEaseOutFunction.html +.. _Quad ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quad/QuadEaseInOutFunction.html +.. _Quart ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quart/QuartEaseInFunction.html +.. _Quart ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quart/QuartEaseOutFunction.html +.. _Quart ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quart/QuartEaseInOutFunction.html +.. _Quint ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quint/QuintEaseInFunction.html +.. _Quint ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quint/QuintEaseOutFunction.html +.. _Quint ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/quint/QuintEaseInOutFunction.html +.. _Sine ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/sine/SineEaseInFunction.html +.. _Sine ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/sine/SineEaseOutFunction.html +.. _Sine ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/sine/SineEaseInOutFunction.html +.. _Back ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/back/BackEaseInFunction.html +.. _Back ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/back/BackEaseOutFunction.html +.. _Back ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/back/BackEaseInOutFunction.html +.. _Bounce ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/bounce/BounceEaseInFunction.html +.. _Bounce ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/bounce/BounceEaseOutFunction.html +.. _Bounce ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/bounce/BounceEaseInOutFunction.html +.. _Elastic ease-in: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/elastic/ElasticEaseInFunction.html +.. _Elastic ease-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/elastic/ElasticEaseOutFunction.html +.. _Elastic ease-in-out: https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/elastic/ElasticEaseInOutFunction.html +.. _Motion.getValue(long): https://repository.microej.com/javadoc/microej_5.x/apis/ej/motion/Motion.html#getValue-long- + +.. |startTable| raw:: html + +
+ +.. |secondColumn| raw:: html + + + +.. |thirdColumn| raw:: html + + + +.. |endTable| raw:: html + +
+ +.. + | Copyright 2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/ApplicationDeveloperGuide/UI/Motion/images/back-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/back-ease-in-out.svg new file mode 100644 index 000000000..0cec14cc9 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/back-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/back-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/back-ease-in.svg new file mode 100644 index 000000000..ed0b6dc6d --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/back-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/back-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/back-ease-out.svg new file mode 100644 index 000000000..5045a5fe8 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/back-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-in-out.svg new file mode 100644 index 000000000..c46d57b84 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-in.svg new file mode 100644 index 000000000..da8563571 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-out.svg new file mode 100644 index 000000000..4d7311c78 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/bounce-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-in-out.svg new file mode 100644 index 000000000..7a8d736e4 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-in.svg new file mode 100644 index 000000000..4c1c6fdfe --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-out.svg new file mode 100644 index 000000000..15d30563c --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/circ-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/constant.svg b/ApplicationDeveloperGuide/UI/Motion/images/constant.svg new file mode 100644 index 000000000..dd282e1a2 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/constant.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-in-out.svg new file mode 100644 index 000000000..a02251eae --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-in.svg new file mode 100644 index 000000000..0effec8a8 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-out.svg new file mode 100644 index 000000000..59f1ca7d2 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/cubic-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-in-out.svg new file mode 100644 index 000000000..6a36a58e9 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-in.svg new file mode 100644 index 000000000..aabba5ce0 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-out.svg new file mode 100644 index 000000000..d7f87ffc1 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/elastic-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-in-out.svg new file mode 100644 index 000000000..2a4d49092 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-in.svg new file mode 100644 index 000000000..cccd68281 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-out.svg new file mode 100644 index 000000000..2885c4146 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/expo-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/linear.svg b/ApplicationDeveloperGuide/UI/Motion/images/linear.svg new file mode 100644 index 000000000..e7c10f4a2 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/linear.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-in-out.svg new file mode 100644 index 000000000..2484cd49f --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-in.svg new file mode 100644 index 000000000..7250fa738 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-out.svg new file mode 100644 index 000000000..5e3498b8a --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quad-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-in-out.svg new file mode 100644 index 000000000..740175394 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-in.svg new file mode 100644 index 000000000..69f668726 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-out.svg new file mode 100644 index 000000000..823064506 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quart-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-in-out.svg new file mode 100644 index 000000000..344223557 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-in.svg new file mode 100644 index 000000000..dde1b1bad --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-out.svg new file mode 100644 index 000000000..a9ff43370 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/quint-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-in-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-in-out.svg new file mode 100644 index 000000000..da22a2e4c --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-in-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-in.svg b/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-in.svg new file mode 100644 index 000000000..daee6fd98 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-in.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-out.svg b/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-out.svg new file mode 100644 index 000000000..44dc78686 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/images/sine-ease-out.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/ApplicationDeveloperGuide/UI/Motion/index.rst b/ApplicationDeveloperGuide/UI/Motion/index.rst new file mode 100644 index 000000000..6a2b32bc8 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/index.rst @@ -0,0 +1,22 @@ +.. _motion: + +Motion +====== + +Motion is a library that provides some of the most commonly used easing functions and allows users to define new ones. + +Easing functions help to mimic the movement of real objects, which allows for the creation of appealing visual animations. +The library can also be useful for other purposes such as defining non-linear gradients for example. + +.. toctree:: + :maxdepth: 2 + + usage + concepts + +.. + | Copyright 2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/ApplicationDeveloperGuide/UI/Motion/usage.rst b/ApplicationDeveloperGuide/UI/Motion/usage.rst new file mode 100644 index 000000000..d4aab3b17 --- /dev/null +++ b/ApplicationDeveloperGuide/UI/Motion/usage.rst @@ -0,0 +1,27 @@ +Usage +===== + +To use the Motion library, add `Motion library module`_ to the project build file: + +.. tabs:: + + .. tab:: Gradle (build.gradle.kts) + + .. code-block:: java + + implementation("ej.library.ui:motion:4.0.1") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + + +.. _Motion library module: https://repository.microej.com/modules/ej/library/ui/motion/ + +.. + | Copyright 2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/ApplicationDeveloperGuide/UI/Simulation/flush-visualizer.rst b/ApplicationDeveloperGuide/UI/Simulation/flush-visualizer.rst index aeed28aad..07bea9b4c 100644 --- a/ApplicationDeveloperGuide/UI/Simulation/flush-visualizer.rst +++ b/ApplicationDeveloperGuide/UI/Simulation/flush-visualizer.rst @@ -37,9 +37,13 @@ Confirm it by measuring the time spent drawing vs. the time spent elsewhere betw Installation ------------ -Set the option ``ej.fp.display.flushVisualizer`` to ``true`` to enable the flush vizualizer. +The Flush Visualizer option is available for the ``Display`` widget in +`frontpanel widget module `__ +version 4.+ for UI Pack 14.0.0 or later. -This option is available for the ``Display`` widget in `frontpanel widget module `__ version 4.+ for UI Pack 14.0.0 or later. +Set the option ``ej.fp.display.flushVisualizer`` to ``true`` to enable the flush visualizer. + +Refer to the :ref:`application_options` documentation to set the option. Usage ----- @@ -49,6 +53,9 @@ Usage .. image:: images/MicroUIFlushVisualizerApplicationOutputFolder.png +.. note:: + + Since MICROEJ SDK 6, the application output folder is located under the ``build/output/`` folder. Limitations ----------- diff --git a/ApplicationDeveloperGuide/UI/ui.rst b/ApplicationDeveloperGuide/UI/ui.rst index 0bd6e51e3..db2420aa9 100644 --- a/ApplicationDeveloperGuide/UI/ui.rst +++ b/ApplicationDeveloperGuide/UI/ui.rst @@ -24,6 +24,7 @@ The following schema shows the overall architecture and modules: MicroUI/index MicroVG/index + Motion/index MWT/index Widgets/index Simulation/index diff --git a/ApplicationDeveloperGuide/buildOutputFiles.rst b/ApplicationDeveloperGuide/buildOutputFiles.rst index 65ef53f5e..e0f6b25a2 100644 --- a/ApplicationDeveloperGuide/buildOutputFiles.rst +++ b/ApplicationDeveloperGuide/buildOutputFiles.rst @@ -43,6 +43,7 @@ After :ref:`building ` the Standalone Application, the publish Published Standalone Application Module Files +.. _soar_map_file: The SOAR Map File ~~~~~~~~~~~~~~~~~ diff --git a/Tutorials/tutorialInstrumentJavaCodeForLogging.rst b/ApplicationDeveloperGuide/codeInstrumentationForLogging.rst similarity index 91% rename from Tutorials/tutorialInstrumentJavaCodeForLogging.rst rename to ApplicationDeveloperGuide/codeInstrumentationForLogging.rst index 695c97d16..a125e70d2 100644 --- a/Tutorials/tutorialInstrumentJavaCodeForLogging.rst +++ b/ApplicationDeveloperGuide/codeInstrumentationForLogging.rst @@ -1,19 +1,10 @@ -.. _tutorial_instrument_java_code_for_logging: +.. _codeInstrumentationForLogging: -Instrument Java Code for Logging +Code Instrumentation for Logging ================================ This document explains how to add logging and tracing to MicroEJ applications and libraries with three different solutions. The aim is to help developers to report precise execution context for further debugging and monitoring. - -Intended Audience ------------------ - -The audience for this document is application developers who are looking for ways to add logging to their MicroEJ applications and libraries. - -It should also be of interest to Firmware engineers how are looking for adjusting the log level while keeping low memory footprint and good performances. - - Introduction ------------ @@ -29,13 +20,13 @@ However, this is not desirable when writing production-grade code, where it shou Overview -------- -In this tutorial, we will describe 3 ways for logging data: +This documentation describes 3 ways for logging data: - Using `Trace`_ library: a real-time event recording library designed for performance and interaction analysis. - Using `Message`_ library: a lightweight and simple logging library. - Using `Logging`_ library: a complete and highly configurable standard logging library. -Through this tutorial, we will illustrate the usage of each library by instrumenting the following code snippet: +The use of each library will be illustrated by instrumenting the following code snippet: .. code-block:: java @@ -75,11 +66,21 @@ Its features and principles are described in the :ref:`event-tracing` section. Here is a short example of how to use this library to log the entry/exit of the ``switchState()`` method: -#. Add the following dependency to the ``module.ivy``: +#. To use this library, add the following line to the project build file: + + .. tabs:: + + .. tab:: Gradle (build.gradle.kts) - .. code-block:: xml + .. code-block:: kotlin - + implementation("ej.api:trace:1.1.1") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + #. Start by initializing a `Tracer`_ object: @@ -119,11 +120,7 @@ Here is a short example of how to use this library to log the entry/exit of the The `Tracer`_ object records the entry/exit of method ``switchState`` with event ID ``0``. -#. Finally, to enable the MicroEJ Core Engine trace system, set the ``core.trace.enabled`` :ref:`option ` to ``true``. - This can be done from a :ref:`launch configuration `: check :guilabel:`Runtime` > :guilabel:`Enable execution traces` option. - - .. image:: images/tuto_microej_trace_property.png - :align: center +#. Finally, to enable the MicroEJ Core Engine trace system, set the ``core.trace.enabled`` :ref:`option ` to ``true``. This produces the following output: @@ -134,7 +131,7 @@ This produces the following output: .. note:: - The default Platform implementation of the `Trace`_ library prints the events to the console. + The default VEE Port implementation of the `Trace`_ library prints the events to the console. See :ref:`trace_implementations` for other available implementations such as :ref:`systemview` tool. .. _Tracer: https://repository.microej.com/javadoc/microej_5.x/apis/ej/trace/Tracer.html @@ -166,11 +163,22 @@ Principles: Here is a short example of how to use this library to log the entry/exit of the ``switchState()`` method: -#. To use this library, add this dependency line in the ``module.ivy``: +#. To use this library, add the following line to the project build file: + + .. tabs:: + + .. tab:: Gradle (build.gradle.kts) + + .. code-block:: kotlin + + implementation("ej.library.runtime:message:2.2.1") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + - .. code-block:: xml - - #. Call the message API to log some info: @@ -228,11 +236,21 @@ The ``ej.library.eclasspath.logging`` `Logging`_ library implements a subset of Here is a short example of how to use this library to log the entry/exit of the ``switchState()`` method: -#. Add the following dependency to the ``module.ivy``: +#. To use this library, add the following line to the project build file: + + .. tabs:: - .. code-block:: xml + .. tab:: Gradle (build.gradle.kts) - + .. code-block:: kotlin + + implementation("ej.library.eclasspath:logging:1.2.1") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + #. Call the logging API to log some info text: @@ -292,10 +310,6 @@ When this boolean constant is detected to be ``false``, the wrapped code becomes #. Let's consider a constant ``com.mycompany.logging`` declared as ``false`` in a resource file named ``example.constants.list``. - .. image:: images/tuto_microej_trace_constant.png - :align: center - - #. Wrap the log code by an ``if`` statement, as follows: .. code-block:: java diff --git a/Tutorials/tutorialExploreDataSerializationFormats.rst b/ApplicationDeveloperGuide/dataSerializationLibraries.rst similarity index 82% rename from Tutorials/tutorialExploreDataSerializationFormats.rst rename to ApplicationDeveloperGuide/dataSerializationLibraries.rst index 682239bac..0cf7f112b 100644 --- a/Tutorials/tutorialExploreDataSerializationFormats.rst +++ b/ApplicationDeveloperGuide/dataSerializationLibraries.rst @@ -1,15 +1,9 @@ -Explore Data Serialization Formats -================================== +Data Serialization +================== -This tutorial highlights some data serialization formats that are provided on MicroEJ Central Repository and their usage through basic code samples. +This documentation highlights some data serialization formats that are provided on MicroEJ Central Repository and their usage through basic code samples. -Intended Audience ------------------ - -The audience for this document is Application engineers who want to implement data serialization. -In addition, this tutorial should be of interest to software architects who are looking for a suitable data format for their use case. - -.. _tutorial_xml: +.. _data_serialization_xml: XML --- @@ -19,12 +13,22 @@ XML XML Module ~~~~~~~~~~ -The `XML Module`_ must be added to the :ref:`module.ivy ` of the MicroEJ -Application project to use the KXML library. +To use the `XML Module`_, add the following line to the project build file: -:: + .. tabs:: + + .. tab:: Gradle (build.gradle.kts) + + .. code-block:: kotlin + + implementation("org.kxml2:kxml2:2.3.2") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + - .. _XML Module: https://repository.microej.com/modules/org/kxml2/kxml2/ @@ -32,9 +36,9 @@ Example Of Use ~~~~~~~~~~~~~~ An example is available at https://github.com/MicroEJ/Example-XML. -It presents how to use XML data exchange for your MicroEJ Application. It also details how to use the `KXmlParser `_ module. +It presents how to use XML data exchange for your Application. It also details how to use the `KXmlParser `_ module. -The example parses a short poem written in XML and prints the result on the standard output. The project can run on any MicroEJ Platform (no external dependencies). +The example parses a short poem written in XML and prints the result on the standard output. The project can run on any VEE Port (no external dependencies). :: @@ -102,7 +106,7 @@ Running ``MyXmlPullApp`` gives more details on the XML parsing and should print SUCCESS -.. _tutorial_json: +.. _data_serialization_json: JSON ---- @@ -120,12 +124,22 @@ JSON is easily readable by humans compared to XML. To parse this data format, se JSON Module ~~~~~~~~~~~ -The `JSON Module`_ must be added to the :ref:`module.ivy ` of the MicroEJ -Application project to use the JSON library. +To use the `JSON Module`_, add the following line to the project build file: -:: + .. tabs:: + + .. tab:: Gradle (build.gradle.kts) + + .. code-block:: kotlin + + implementation("org.json.me:json:1.4.0") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + - The instantiation and use of the parser is pretty straightforward. First you need to get the JSON content as a ``String``, and then create a `JSONObject`_ instance with the string. @@ -243,7 +257,7 @@ The example below will parse the file, browse the resulting data structure (``or } -The execution of this example on the MicroEJ Simulator should print the following trace: +The execution of this example on the Simulator should print the following trace: :: @@ -255,7 +269,7 @@ The execution of this example on the MicroEJ Simulator should print the followin SUCCESS -.. _tutorial_cbor: +.. _data_serialization_cbor: CBOR ---- @@ -267,12 +281,22 @@ The `CBOR (Concise Binary Object Representation) `_ binary dat CBOR Module ~~~~~~~~~~~ -The `CBOR Module`_ must be added to the :ref:`module.ivy ` of the MicroEJ -Application project to use the CBOR library. +To use the `CBOR Module`_, add the following line to the project build file: -:: + .. tabs:: + + .. tab:: Gradle (build.gradle.kts) + + .. code-block:: kotlin + + implementation("ej.library.iot:cbor:1.2.0") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + - .. _CBOR Module: https://repository.microej.com/modules/ej/library/iot/cbor/ @@ -280,10 +304,10 @@ Example Of Use ~~~~~~~~~~~~~~ An example is available at https://github.com/MicroEJ/Example-IOT/tree/master/cbor. -It shows how to use the CBOR library in your MicroEJ Application by encoding some data and reading it back, printing it on the standard output both as a raw byte string and in a JSON-like format. -You can use tools like cbor.me to convert the byte string output to a JSON format and check that it matches the encoded data. The project can run on any MicroEJ Platform (no external dependencies). +It shows how to use the CBOR library in your Application by encoding some data and reading it back, printing it on the standard output both as a raw byte string and in a JSON-like format. +You can use tools like cbor.me to convert the byte string output to a JSON format and check that it matches the encoded data. The project can run on any VEE Port (no external dependencies). -The execution of this example on the MicroEJ Simulator should print the following trace: +The execution of this example on the Simulator should print the following trace: :: @@ -313,7 +337,7 @@ The execution of this example on the MicroEJ Simulator should print the followin Another example showing how to use the :ref:`JSON ` module along with the :ref:`CBOR ` module to convert data from JSON to CBOR is available here : https://github.com/MicroEJ/Example-IOT/tree/master/cbor-json. -The execution of this example on the MicroEJ Simulator should print the following trace: +The execution of this example on the Simulator should print the following trace: :: diff --git a/Tutorials/tutorialSoftwareRobot.rst b/ApplicationDeveloperGuide/guiSoftwareRobot.rst similarity index 96% rename from Tutorials/tutorialSoftwareRobot.rst rename to ApplicationDeveloperGuide/guiSoftwareRobot.rst index 8a9db6fb1..5ed4278b5 100644 --- a/Tutorials/tutorialSoftwareRobot.rst +++ b/ApplicationDeveloperGuide/guiSoftwareRobot.rst @@ -1,7 +1,7 @@ -.. _tutorials_software_robot: +.. _guiSoftwareRobot: -How to Test a GUI Application with a (Software) Robot -===================================================== +GUI Software Robot +================== This document presents how to test a GUI application with a software robot for robotic process automation (RPA). @@ -16,15 +16,15 @@ The robot implementation proposed here targets the following errors detection: The following document covers: -* Recording human touch events on the simulator or on the embedded platform -* Running recorded events on the simulator or on the embedded platform +* Recording human touch events on the simulator or on the device +* Running recorded events on the simulator or on the device The following document does not cover: * The display rendering validation (this can be done using the `Test Automation `_ Tool) * Integration of the robot into an automatic JUnit test suite -We will now present the basic architecture and code required to create and to run a robot within a MicroEJ application on the simulator and embedded platform. +We will now present the basic architecture and code required to create and to run a robot within a MicroEJ application on the simulator and on the device. In the following sections, we assume the MicroEJ VEE Port has a display interface and a touch controller. diff --git a/Tutorials/images/json-src-files-folders.png b/ApplicationDeveloperGuide/images/json-src-files-folders.png similarity index 100% rename from Tutorials/images/json-src-files-folders.png rename to ApplicationDeveloperGuide/images/json-src-files-folders.png diff --git a/ApplicationDeveloperGuide/introduction.rst b/ApplicationDeveloperGuide/introduction.rst index 9c2783575..495f2a157 100644 --- a/ApplicationDeveloperGuide/introduction.rst +++ b/ApplicationDeveloperGuide/introduction.rst @@ -22,8 +22,8 @@ resources such as: MicroEJ Applications are developed as standard Java applications on -Eclipse JDT, using Foundation Libraries. MicroEJ SDK allows you to -run / debug / deploy MicroEJ Applications on a MicroEJ Platform. +Eclipse JDT, using Foundation Libraries. The SDK allows you to +run / debug / deploy Applications on a VEE Port. Two kinds of applications can be developed on MicroEJ: MicroEJ Standalone Applications and MicroEJ Sanboxed Applications. diff --git a/ApplicationDeveloperGuide/javaTime.rst b/ApplicationDeveloperGuide/javaTime.rst index e5151c322..2eb088f40 100644 --- a/ApplicationDeveloperGuide/javaTime.rst +++ b/ApplicationDeveloperGuide/javaTime.rst @@ -12,9 +12,9 @@ .. _TimeZone: https://repository.microej.com/javadoc/microej_5.x/apis/java/util/TimeZone.html .. _ZoneRulesException: https://repository.microej.com/javadoc/microej_5.x/apis/java/time/zone/ZoneRulesException.html .. _ZoneRulesProvider: https://repository.microej.com/javadoc/microej_5.x/apis/java/time/zone/ZoneRulesProvider.html +.. _ZoneRules: https://repository.microej.com/javadoc/microej_5.x/apis/java/time/zone/ZoneRules.html .. _ZoneId: https://repository.microej.com/javadoc/microej_5.x/apis/java/time/ZoneId.html .. _ZoneOffset: https://repository.microej.com/javadoc/microej_5.x/apis/java/time/ZoneOffset.html -.. _IANADatabase: https://www.iana.org/time-zones Date and Time ============= @@ -82,13 +82,13 @@ To use the `time + @@ -305,79 +305,135 @@ For example, it can represent periods such as 2 years, 3 months, and 5 days. Time Zone Support ----------------- -The library relies on a time zone rules provider to supply the rules and data required for managing time zones. -The zone rules provider offers information about how time zones are defined, including their offsets from Coordinated Universal Time (UTC), daylight saving time (DST) rules and historical changes. - The Time API introduces multiple types for time zone management: -- `ZoneId`_ : represents a time zone identifier (e.g., ``Africa/Johannesburg``). -- `ZoneOffset`_ : represents a fixed time zone offset from Coordinated Universal Time (UTC). -- `ZonedDateTime`_ : represents the local time for a specific location. -- `ZoneRulesProvider`_ : foundation for supplying time zone rules and data and implementing custom time zone rules providers. +- `ZoneId`_ : represents a time zone identifier: a fixed offset (e.g., ``+0200``) or a geographical region (e.g., ``Africa/Johannesburg``). +- `ZoneOffset`_ : represents a fixed time zone offset from UTC, usually a fixed number of hours and minutes. +- `ZonedDateTime`_ : a date time with a time zone: the combination of a `LocalDateTime`_ and a `ZoneId`_. +- `ZoneRules`_ : defines the offsets from UTC, the daylight saving time rules, and how they change over time, for a specific time zone. +- `ZoneRulesProvider`_ : provides the time zone rules to all the zone-aware classes of the library. Meant to be implemented by custom time zone rule providers. -All the zone-aware classes of the library rely on the underlying time zone rules provider to supply accurate information about the time zone. +Default Zone Rules Provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Java SE 8 and higher have a default provider that delivers zone rules for the time zones defined by `IANADatabase`_. -The ``time`` library does not use this provider as the default (see :ref:`Restrictions `). -Instead, the library comes with a default provider which is very lightweight and designed to handle only the time zone rules for the "GMT" (Greenwich Mean Time) zone. +By default, the library uses a lightweight provider designed to handle only the time zone rules for ``GMT`` (Greenwich Mean Time). This is suitable for operations on dates and times that do not depend on time zone considerations. -Any attempt to use another zone ID will throw a `ZoneRulesException`_ because the ID is unknown. +This provider only supports the ``GMT`` zone ID. Any attempt to get a different zone ID will throw a `ZoneRulesException`_. For example, .. code-block:: java - // Displaying available time zones - will list a single item: "GMT" - Set timeZones = ZoneId.getAvailableZoneIds(); - for (String timeZone : timeZones) { - System.out.println(timeZone); - } + ZoneId.of("GMT"); // ok + ZoneId.of("+0200"); // ok + ZoneId.of("GMT+0530"); // ok + ZoneId.of("PST"); // throws ZoneRulesException + ZoneId.of("CST-0115"); // throws ZoneRulesException + ZoneId.of("Asia/Tokyo"); // throws ZoneRulesException - // Creating ZonedDateTime instance - will throw a ZoneRulesException - ZonedDateTime specificDateTime = ZonedDateTime.of(2023, 7, 15, 14, 30, 0, 0, ZoneId.of("Europe/Dublin")); // July 15, 2023, 2:30 PM in Dublin + Set zoneIds = ZoneId.getAvailableZoneIds(); // returned set contains only "GMT" - // Creating ZoneId instance from a region ID - will throw a ZoneRulesException - ZoneId tokyoTimeZone = ZoneId.of("Asia/Tokyo"); +TZDB Zone Rules Provider +~~~~~~~~~~~~~~~~~~~~~~~~ +The library also defines a provider of zone rules for the time zones defined in the `IANA Time Zone Database `_ (TZDB). -However, you can define a custom default provider for loading time zone rules. -First, create a class that extends `ZoneRulesProvider`_ and defines custom zone rules like in the example after: +The TZDB provider reads the zones and rules from a raw resource at runtime. +Compared to the ``TzdbZoneRulesProvider`` of Java SE distributions, this implementation uses less Java heap at runtime, making it more suitable for embedded devices. -.. code-block:: java +.. warning:: + The TZDB provider requires a target VEE Port that uses an architecture version ``8.1.1`` minimum (for ``8.x``), or ``7.20.5`` minimum (for ``7.x``). - public class CustomZoneRulesProvider extends ZoneRulesProvider { +Using the TZDB Provider +^^^^^^^^^^^^^^^^^^^^^^^ - @Override - protected Set provideZoneIds() { - Set set = new HashSet<>(1); - set.add("CustomZone"); - return set; - } +To use this provider, set the constant ``java.time.zone.DefaultZoneRulesProvider`` to ``java.time.zone.TzdbZoneRulesProvider`` in a ``*.constants.list`` file, like below: - @Override - protected ZoneRules provideRules(String zoneId, boolean forCaching) { - if ("CustomZone".equals(zoneId)) { - // this custom zone has a fixed offset (+02:00) - return ZoneRules.of(ZoneOffset.ofHours(2)); - } - throw new ZoneRulesException("Unknown zone ID"); - } +.. code-block:: jproperties - @Override - protected NavigableMap provideVersions(String zoneId) { - throw new ZoneRulesException("No version history available for this zone ID " + zoneId); - } - } + java.time.zone.DefaultZoneRulesProvider=java.time.zone.TzdbZoneRulesProvider -To make this class the default provider, set the constant ``java.time.zone.DefaultZoneRulesProvider`` to be the Full Qualified name of the custom provider class. +It is also required to add the class name ``java.time.zone.TzdbZoneRulesProvider`` to a ``*.types.list`` file: the class name is required to instantiate the provider and can not be known at compile-time. -Here is an example of a ``xxx.constants.list`` file with the constant in an application: +The raw resource from which the provider reads the zone rules is generated from the timezone database file included in the JDK/JRE installation (``tzdb.dat``). +To generate the resource and use it in an application, do the following: -.. code-block:: jproperties +1. Locate the ``tzdb.dat`` file in a local JDK/JRE installation (``path/to/JRE/lib/tzdb.dat``), +2. Add the ``tzdb.dat`` file to the application resources (e.g., ``src/main/resources/com/mycompany/tzdb.dat``), +3. Create a ``*.tzdb.list`` file in the application resources (e.g., ``src/main/resources/com/mycompany/myapp.tzdb.list``), +4. Open the ``*.tzdb.list`` file and add the path to the ``tzdb.dat`` file (e.g., ``/com/mycompany/tzdb.dat``). - java.time.zone.DefaultZoneRulesProvider=com.mycompany.CustomZoneRulesProvider +The resource will be automatically generated when building the application or running it in the Simulator. +By default, it will be embedded in the application binary (as an :ref:`internal resource`). +For reference, the size of the resource is 100 KB for version ``2024a``. -.. note:: - Custom time zone rules providers are usually made for specific needs or to work with non-standard data sources. +.. note:: + + To get a ``tzdb.dat`` with the most current timezone data available, use the `TZUpdater tool `_ and run the following command: + + .. code:: + + java -jar tzupdater.jar -l + + The TZUpdater tool updates the JDK/JRE instance that is used to execute the tool: copy ``path/to/JRE/lib/tzdb.dat`` into the application resources, as described above. + + In addition, you can check that the version of the timezone data is correct in the logs of the Add-on Processor that generates the raw resource. + + .. tabs:: + + .. tab:: SDK 6 + + When running on Simulator or building an executable in verbose mode (with the ``--info`` Gradle option), look in the console for an output similar to: + + .. code:: text + + [myapp:tzdb] Successfully deserialized TZDB data: version = 2024a, zones count = 603, resource buffer size = 102532 + + where ``2024a`` is the version of the timezone data in this example. + + .. tab:: SDK 5 + + The Add-on Processor is executed when changes occur in the resources files. + Open the Add-on Processor console and set the log level to ``debug``. + After copying a ``tzdb.dat`` file in the resources files, look in the console for an output similar to: + + .. code:: text + + [myapp:tzdb] Successfully deserialized TZDB data: version = 2024a, zones count = 603, resource buffer size = 102532 + + where ``2024a`` is the version of the timezone data in this example. + + +If the TZDB provider can't find the resource, it will throw an exception at runtime: + +.. code-block:: java + + Exception in thread "main" java.lang.ExceptionInInitializerError: java.lang.IllegalStateException: Cannot open the tzdb binary resource + +In this case, follow the steps described above to generate the resource, and make sure that the resource is available at runtime: +when the resource is internal, the ``tzdb`` resource should be listed in the ``Application Resources`` group of the :ref:`SOAR.map` file. + +Loading the TZDB Data as an External Resource +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The resource can be declared as an external resource to be loaded from another location (e.g. from a FileSystem). +It has to be referenced in a ``*.externresources.list`` file, in which case the SOAR will output the resource in the :ref:`external_resources_folder`. +See :ref:`chapter.microej.applicationResources` for more information about external resources. + +.. warning:: + Loading external resources requires a target VEE Port that uses the :ref:`External Resources Loader`. + +Follow the steps below to declare the ``tzdb`` resource as an external resource: + +- Create a ``*.externresources.list`` file in the ``src/main/resources/`` folder, +- Add the following path to the file: + + .. code:: + + /java/time/zone/tzdb + +- Build the application executable, +- The raw resource is now available in the :ref:`external_resources_folder`. + This resource must be transferred to the target device's memory and loaded from the path ``/java/time/zone/tzdb``, using the :ref:`External Resources Loader`. .. _time_migration_guide: @@ -533,18 +589,18 @@ Restrictions ------------ The library's goal is to offer Application developers an API that closely mirrors the one found in Java SE 8. -However, we had to make the library compatible with both pre-Java 8 features and the constraints found in embedded devices. +However, we had to make the library compatible with both pre-Java 8 features and the constraints found in embedded devices, such as limited memory size. Here are the items where the backport differs from its Java 8 counterpart: - Non-ISO chronologies are not present (`Hijrah`, `Japanese`, `Minguo`, `ThaiBuddhist`). The overwhelming majority of applications use the ISO calendar system. Applications still have the option to introduce their own chronologies. - No formatting or parsing methods (methods ``parse``, ``format``, ``getDisplayName``, ``ofLocale``). -- The default zone-rules provider does not use `IANADatabase`_. This provider loads zone rules from a local TZDB database and it consumes a significant amount of RAM. We plan to add this support shortly. - Removed the method ``ZoneRulesProvider.registerProvider(ZoneRulesProvider provider)``. The unique provider is defined with the constant ``java.time.zone.DefaultZoneRulesProvider``. - Static methods in interfaces are not supported and were removed or moved (see below). - Default methods in interfaces are not supported and were removed (pulled down in concrete types). - Removed static methods ``TemporalAdjusters.ofDateAdjuster(UnaryOperator dateBasedAdjuster)`` and ``WeekFields.of(Locale locale)``. - No overflow checks on calculations (removed ``throws ArithmeticException`` when relevant). Excessively checking for overflow in all calculations can impact performance negatively. -- No null checks on method arguments. Developers are encouraged to use the :ref:`Null Analysis ` tool to detect null access and adhere to the API javadoc specifications. +- No null checks on method arguments. Developers are encouraged to use the :ref:`Null Analysis ` tool to detect null access and adhere to the API Javadoc specifications. +- The classes from the ``java.time.zone`` package do not provide a human readable implementation of ``toString()``. .. note:: For a comprehensive list of restrictions, refer to the ``README`` of the module. diff --git a/ApplicationDeveloperGuide/js/pptx/js_runtime.pptx b/ApplicationDeveloperGuide/js/pptx/kifaru_schema.pptx similarity index 71% rename from ApplicationDeveloperGuide/js/pptx/js_runtime.pptx rename to ApplicationDeveloperGuide/js/pptx/kifaru_schema.pptx index cb439d159..061882631 100644 Binary files a/ApplicationDeveloperGuide/js/pptx/js_runtime.pptx and b/ApplicationDeveloperGuide/js/pptx/kifaru_schema.pptx differ diff --git a/ApplicationDeveloperGuide/libraries.rst b/ApplicationDeveloperGuide/libraries.rst index e27aa428e..f99ba0b2e 100644 --- a/ApplicationDeveloperGuide/libraries.rst +++ b/ApplicationDeveloperGuide/libraries.rst @@ -9,10 +9,10 @@ library is divided into an API and an implementation. A Foundation library API is composed of a name and a 2 digits version (e.g. ``EDC-1.3``) and follows the semantic versioning (``_) specification. A Foundation Library API only contains prototypes without -code. Foundation Library implementations are provided by MicroEJ -Platforms. From a MicroEJ Classpath, Foundation Library APIs +code. Foundation Library implementations are provided by VEE Ports. +From a MicroEJ Classpath, Foundation Library APIs dependencies are automatically mapped to the associated implementations -provided by the Platform or the Virtual Device on which the application +provided by the VEE Port or the Virtual Device on which the application is being executed. A MicroEJ Add-On Library is a MicroEJ library that is implemented on top @@ -39,6 +39,7 @@ To consult its libraries APIs documentation, please visit ``. + Please refer to your VEE Port specific documentation to get the memory mapping of :ref:`MicroEJ Core Engine sections `. .. list-table:: Architecture Limitations @@ -79,6 +79,12 @@ Please consult :ref:`architecture_changelog` for limitations changes on former v * - Number of Java heap Garbage Collection - 3000 [4]_ - unlimited + * - Number of Shielded Plug databases + - unlimited + - unlimited + * - Number of blocks per Shielded Plug database + - 32767 + - 32767 .. [1] diff --git a/ApplicationDeveloperGuide/modulesRepositories.rst b/ApplicationDeveloperGuide/modulesRepositories.rst index 249ffff83..02cd66b98 100644 --- a/ApplicationDeveloperGuide/modulesRepositories.rst +++ b/ApplicationDeveloperGuide/modulesRepositories.rst @@ -53,7 +53,7 @@ It is similar to what `Maven Central Repository `_ - - `CborEncoder class `_ - `CborDecoder class `_ - - - :ref:`CBOR Tutorial ` + - - :ref:`CBOR Documentation ` * - ``JSON`` - JavaScript Object Notation (JSON) encoder and decoder. @@ -89,21 +89,21 @@ Data Serialization Libraries - - `JSONObject class `_ (decoder) - `JSONWriter class `_ (encoder) - - `README `_ - - :ref:`JSON Tutorial ` + - :ref:`JSON Documentation ` * - ``Protocol Buffers`` - Google Protocol Buffers 3 encoder and decoder, supporting files compiled by ``protoc`` with lite plugin. - `protobuf3 `_ - - `CodedInputStream class `_ (decoder) - `CodedOutputStream class `_ (encoder) - - - `Protobuf3 Example `_ + - - `Protobuf3 Documentation `_ * - ``XML`` - eXtensible Markup Language encoder and decoder (`kXML 3 `_). - `kxml2 `_ - - `XmlPullParser class `_ (decoder) - `XmlSerializer class `_ (encoder) - - - :ref:`XML Tutorial ` + - - :ref:`XML Documentation ` Cloud Agent Libraries diff --git a/ApplicationDeveloperGuide/nls.rst b/ApplicationDeveloperGuide/nls.rst index 6dbaddd59..347464baa 100644 --- a/ApplicationDeveloperGuide/nls.rst +++ b/ApplicationDeveloperGuide/nls.rst @@ -1,7 +1,7 @@ .. _chapter.nls: -Native Language Support -======================= +Native Language Support (NLS) +============================= Introduction ------------ @@ -875,6 +875,125 @@ Unless it is also referenced by an ``.externresources.list`` in which case the S This resource is loaded as soon as the BinaryNLS instance is created, in the clinit of the generated NLS interface (see :ref:`Principle `). +Fallback on Default Resource +---------------------------- + +When using a resource referenced as External Resource (``.externresources.list``), the application is not guaranteed to access it at startup (external memory failure, corruption, ...). + +The application can be configured to fallback on a default resource embedded in the Application binary. +This resource can be a "lighter" version of the one loaded using the External Resources Loader (e.g. only embed the English language). + +Usage +^^^^^ + +The procedure below assumes that the application already has localization source files named ``HelloWorldMessages*.po`` that are referenced as External Resource. + +The procedure below explains how to setup the fallback on a default resource embedding the ``en_US`` locale only: + +- Create a new localization source file in the ``src/main/resources`` folder (e.g. ``HelloWorldMessagesDefault_en_US.po``). + This file should contain the same translations as ``HelloWorldMessages_en_US.po``, +- Declare it in the ``*.nls.list`` file (e.g. ``com.microej.example.nls.generated.HelloWorldMessagesDefault``), +- Create a new class that implements the ``NLS`` interface (e.g. ``DefaultNLS``), +- Implement every method, wrapping on ``HelloWorldMessagesDefault``: + +.. code-block:: java + + public class DefaultNLS implements NLS { + + @Override + public String[] getAvailableLocales() { + return HelloWorldMessagesDefault.NLS.getAvailableLocales(); + } + + @Override + public String getDisplayName(String locale) { + return HelloWorldMessagesDefault.NLS.getDisplayName(locale); + } + ... + +- Set the ``DefaultNLS`` class as the default NLS implementation: + + - Create a ``*.properties.list`` file in the ``src/main/resources`` folder (if not already created), + - Add the following property in this file: ``com.microej.binarynls.defaultImplementation=[FULLY QUALIFIED NAME TO DEFAULT IMPLEMENTATION CLASS]`` + (e.g. ``com.microej.binarynls.defaultImplementation=com.microej.example.nls.DefaultNLS``). + +- Declare ``DefaultNLS`` as a :ref:`Required type `: + + - Create a ``*.types.list`` file in the ``src/main/resources`` folder (if not already created), + - Add the fully qualified name of the class (e.g. ``com.microej.example.nls.DefaultNLS``). + +To guarantee the proper application operation, the default translations (``HelloWorldMessagesDefault``) +must be consistent with the translations embedded in External Memory (``HelloWorldMessages``). +In other words, they must contain the exact same set of messages. + +- Add the following code in the ``Main`` class to perform the consistency check at startup: + +.. code-block:: java + + static { + if (HelloWorldMessagesDefault.KeysCRC32 != HelloWorldMessages.KeysCRC32) { + throw new RuntimeException( + "CRC check fail between default and fallback translations. Make sure PO files are aligned."); + } + } + +.. warning:: This implementation only checks the consistency of ``msgid``, it does not check the content of ``msgstr``. PO files should be checked carefully to avoid deviation between translations. + +The logs below are showing the expected behavior when the resource can be loaded or can't be loaded from External Memory: + +.. tabs:: + + .. tab:: Resource Loaded from External Memory + + .. code-block:: console + + MicroEJ START + Available locales: + - en_US + - es_FR + - fr_FR + Saying: + English (US) (en_US) + - Hello, World + - What's up? + Español (es_FR) + - Hola, Mundo + - ¿ Qué tal ? + Français (fr_FR) + - Bonjour, Le Monde + - Ça va ? + MicroEJ END (exit code = 0) + + .. tab:: Fallback on Default Resource (External Memory failure) + + .. code-block:: console + + MicroEJ START + NLS-PO:I=6 + Exception in thread "main" java.io.IOException: NLS-PO:S=1 + at java.lang.System.getStackTrace(Unknown Source) + at java.lang.Throwable.fillInStackTrace(Throwable.java:82) + at java.lang.Throwable.(Throwable.java:37) + at java.lang.Exception.(Exception.java:18) + at java.io.IOException.(IOException.java:18) + at com.microej.nls.BinaryNLS.loadBinFile(BinaryNLS.java:385) + at com.microej.nls.BinaryNLS.(BinaryNLS.java:203) + at com.microej.nls.BinaryNLS.newBinaryNLSInternal(BinaryNLS.java:161) + at com.microej.nls.BinaryNLS.newBinaryNLS(BinaryNLS.java:155) + at com.microej.example.nls.generated.HelloWorldMessages.(HelloWorldMessages.java:19) + at java.lang.Thread.execClinit(Unknown Source) + at java.lang.Thread.clinitWrapper(Thread.java:483) + at java.lang.Thread.callWrapper(Thread.java:449) + + Available locales: + - en_US + Saying: + English (US) (en_US) + - Hello, World + - What's up? + MicroEJ END (exit code = 0) + + .. _section.nls.limitations: Limitations diff --git a/ApplicationDeveloperGuide/runtime.rst b/ApplicationDeveloperGuide/runtime.rst index a2af76762..6d60e1d70 100644 --- a/ApplicationDeveloperGuide/runtime.rst +++ b/ApplicationDeveloperGuide/runtime.rst @@ -11,7 +11,7 @@ MicroEJ allows to develop Applications in the `Java® Language Specification ver 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 ` before execution: ``.class`` files and some other application-related files (see :ref:`Classpath ` chapter) are linked to produce the final binary file that the :ref:`Core Engine ` will execute. -.. note:: When opened in the SDK, 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`. +.. 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`. .. [1] The JDT compiler from the Eclipse IDE. @@ -65,13 +65,13 @@ The `EDC API Module`_ must be added to the project build file of the Application .. tabs:: - .. tab:: Gradle (build.gradle.kts) + .. tab:: SDK 6 .. code-block:: java implementation("ej.api:edc:1.3.5") - .. tab:: MMM (module.ivy) + .. tab:: SDK 5 .. code-block:: xml @@ -119,13 +119,13 @@ Project to use the `BON API Module`_: .. tabs:: - .. tab:: Gradle (build.gradle.kts) + .. tab:: SDK 6 .. code-block:: java implementation("ej.api:edc:1.3.5") - .. tab:: MMM (module.ivy) + .. tab:: SDK 5 .. code-block:: xml diff --git a/ApplicationDeveloperGuide/sandboxedAppSharedInterface.rst b/ApplicationDeveloperGuide/sandboxedAppSharedInterface.rst index 2d814f915..9214955bf 100644 --- a/ApplicationDeveloperGuide/sandboxedAppSharedInterface.rst +++ b/ApplicationDeveloperGuide/sandboxedAppSharedInterface.rst @@ -94,6 +94,9 @@ interface. For example: void foo(); } +A Shared Interface includes all methods it declares, along with those inherited from its super types. +It can extend any interface, including Feature interfaces (which may or may not be declared as Shared Interfaces) and Kernel interfaces. + Some restrictions apply to Shared Interfaces compared to standard Java interfaces: @@ -103,8 +106,16 @@ interfaces: Implement the Proxy Class ^^^^^^^^^^^^^^^^^^^^^^^^^ -A proxy class is implemented and executed on the client side, each -method of the implemented interface must be defined according to the +A proxy class is implemented and executed on the client side. + +with the following specification: + +- its fully qualified name is the shared interface fully qualified name append with ``Proxy``. +- it extends the `Proxy`_ class. +- it implements the Shared Interface +- it provides an implementation of all interface methods + +Each method of the implemented interface must be defined according to the following pattern: .. code:: java @@ -117,7 +128,10 @@ following pattern: try { invoke(); // perform remote invocation } catch (Throwable e) { - e.printStackTrace(); // handle errors + // Handle any errors thrown during the remote call, including dead Feature. + // Implement a behavior that complies with the method specification. + // i.e. return a valid error code or throw a documented exception. + // Logging traces for debug can also be added here. } } } @@ -250,7 +264,8 @@ to be transferred. - Any Class, Array or Interface - Kernel - Application - - Kernel specific or forbidden + - Kernel specific. Converted to a target Feature object if the Kernel has registered a + :ref:`Kernel type converter `, otherwise Forbidden. - @@ -264,14 +279,14 @@ to be transferred. - Arrays of references - Any - Application - - Clone and transfer rules applied again on each element + - Clone and transfer rules applied again on each element (recursively) - - Shared Interface - Application - Application - - Passing by indirect reference (Proxy creation) + - Passing by indirect reference (Proxy creation). - @@ -282,23 +297,16 @@ to be transferred. Objects created by an Application which type is owned by the Kernel can be transferred to another Application provided this has been -authorized by the Kernel. The list of Kernel types that can be -transferred is Kernel specific, so you have to consult your Kernel -specification. When an argument transfer is forbidden, the call is +authorized by the Kernel. When an argument transfer is forbidden, the call is abruptly stopped and an `java.lang.IllegalAccessError`_ is thrown by the :ref:`Core Engine `. .. _java.lang.IllegalAccessError: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/IllegalAccessError.html -.. note:: - - For these types to be transferable, a dedicated :ref:`Kernel Type Converter ` must have been registered in - the Kernel. - -The table below lists typical Kernel types allowed to be transferred through a Shared Interface -call on `Evaluation Kernels ` distributed by MicroEJ Corp. +The list of Kernel types that can be transferred is Kernel specific, so you have to consult your Kernel specification. +The table below lists some well-known types that your Kernel likely can allow to be transferred through a Shared Interface, along with their behaviors. [#1]_. -.. list-table:: MicroEJ Evaluation Kernels Rules for Transferable Types +.. list-table:: Transfer Rules for well-known Kernel Types :header-rows: 1 - - Type @@ -330,6 +338,8 @@ call on `Evaluation Kernels `_ - Clone by copy with recursive keys and values conversion +.. [#1] For these types to be transferable, a dedicated :ref:`Kernel Type Converter ` must have been registered in the Kernel. + .. _section.proxy.implementation: Implementing the Proxy Class @@ -377,12 +387,17 @@ and are named ``invokeXXX()`` where ``XXX`` is the kind of return type. .. _invokeDouble(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Proxy.html#invokeDouble-- .. _invokeFloat(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Proxy.html#invokeFloat-- + As this class is part of the Application, the developer has the full control on the Proxy implementation and is free to insert additional code such as logging calls and errors for example. It is also possible to have different proxy implementations for the same Shared Interface in different applications. + + +.. _Proxy: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Proxy.html + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/ApplicationDeveloperGuide/testsuiteEngine.rst b/ApplicationDeveloperGuide/testsuiteEngine.rst index 2f1760a72..479e02d29 100644 --- a/ApplicationDeveloperGuide/testsuiteEngine.rst +++ b/ApplicationDeveloperGuide/testsuiteEngine.rst @@ -21,7 +21,7 @@ projects within the configuration of a generic Ant file. :width: 500px The MicroEJ Test Suite Engine is already pre-configured for running -test suites on a MicroEJ Platform (either on Simulator or on Device). +test suites on a VEE Port (either on Simulator or on Device). - For Application and Libraries, refer to :ref:`application_testsuite` section. diff --git a/ApplicationDeveloperGuide/tools.rst b/ApplicationDeveloperGuide/tools.rst index 7c63212e9..1f80d0348 100644 --- a/ApplicationDeveloperGuide/tools.rst +++ b/ApplicationDeveloperGuide/tools.rst @@ -4,12 +4,14 @@ Development Tools .. toctree:: :maxdepth: 2 + codeInstrumentationForLogging trace debuggerProxy dependencyDiscoverer linker testsuiteEngine heapUsageMonitoring + guiSoftwareRobot .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free diff --git a/ApplicationDeveloperGuide/trace.rst b/ApplicationDeveloperGuide/trace.rst index 2ef0d115e..af826a3ec 100644 --- a/ApplicationDeveloperGuide/trace.rst +++ b/ApplicationDeveloperGuide/trace.rst @@ -32,7 +32,7 @@ Event Tracing can be accessed from two APIs: -- A C API, provided by the Platform header file named ``LLTRACE_impl.h``. +- A C API, provided by the Foundation Library header file named ``LLTRACE_impl.h``. .. _Trace API module: https://repository.microej.com/modules/ej/api/trace/ @@ -147,7 +147,7 @@ Examples: .. _trace_implementations: -Platform Implementation +VEE Port Implementation ======================= By default, when enabled, the Trace API displays a message in the standard output for every ``recordEvent(...)`` and ``recordEventEnd(...)`` method calls. @@ -155,14 +155,14 @@ By default, when enabled, the Trace API displays a message in the standard outpu It does not print a timestamp when displaying the trace message because it can drastically affect execution performances. It only prints the ID of the recorded event followed by the values given in parameters. -A Platform can connect its own implementation by overriding the functions defined in the ``LLTRACE_impl.h`` file. +A VEE Port can connect its own implementation by overriding the functions defined in the ``LLTRACE_impl.h`` file. MicroEJ Corp. provides an implementation that redirects the events to :ref:`systemview` tool, the real-time recording and visualization tool from `Segger `_. It is perfect for a finer understanding of the runtime behavior by showing events sequence and duration. A implementation example for the `NXP OM13098 development board `_ with SystemView support is available `here `__. -Please contact :ref:`our support team ` for more information about how to integrate this Platform module. +Please contact :ref:`our support team ` for more information about how to integrate this module. Advanced Event Tracing ====================== diff --git a/KernelDeveloperGuide/applicationSecurityPolicy.rst b/KernelDeveloperGuide/applicationSecurityPolicy.rst new file mode 100644 index 000000000..387b44740 --- /dev/null +++ b/KernelDeveloperGuide/applicationSecurityPolicy.rst @@ -0,0 +1,332 @@ +.. _applicationSecurityPolicy: + +Define a Security Policy +======================== + +A security policy allows the Kernel to prevent an Application from accessing resources or calling specific APIs. +Whereas APIs :ref:`exposed by the Kernel ` allows to control at build-time, the security policy here controls the APIs called at runtime. + +Defining a security policy is done by implementing the standard `SecurityManager`_ class. +Basically, all sensitive APIs exposed by the Kernel have already been protected by a :ref:`Permission Check `. +Each time an Application calls such API, the Security Manager `SecurityManager.checkPermission(Permission)`_ implementation verifies that the requested permission has been granted to the Application. + +Register a Security Manager +--------------------------- + +The first step for the Kernel is to register a `SecurityManager`_ implementation. +Usually this is done in the Kernel boot sequence, before starting to run Applications. +However, the Security Manager can be updated at any-time, and a Kernel can also register different implementations during its execution. + +For the purpose of ROM footprint optimization, permission checks calls are disabled by default to avoid extra code processing if the system owner does not want to use the Security Manager. +In order to activate this feature, set the :ref:`option_enable_security_manager` option. + +Once the Security Manager checks are enabled, you can then implement your own security policy. + +To apply a security policy, instantiate a `SecurityManager`_ and register it with `System.setSecurityManager(SecurityManager)`_ method. + +.. code-block:: java + + // create an instance of SecurityManager + SecurityManager sm = new SecurityManager() { + @Override + public void checkPermission(java.security.Permission perm) { + // implement here the Application Security Policy + }; + }; + // set the Security Manager + System.setSecurityManager(sm); + +The next section will guide you to implement the desired security policy. + +Implement a Security Manager +---------------------------- + +The implementation of the `SecurityManager.checkPermission(Permission)`_ method first retrieves the owner of the requested Permission, +then checks if it is a Feature (not the Kernel), and finally, checks the permission according to the given Feature. + +The following code snippet shows the typical implementation: + +.. code-block:: java + + public class MyKernelSecurityManager extends SecurityManager { + + @Override + public void checkPermission(Permission perm) { + Module caller = Kernel.getContextOwner(); + if(caller == Kernel.getInstance()) { + // Kernel has all the rights: no checks + } + else{ + Feature callerApp = (Feature)caller; + Kernel.enter(); + if(!isAllowed(callerApp, perm)) { + throw new SecurityException(); + } + } + } + + private boolean isAllowed(Feature callerApp, Permission perm) { + // implement here the Application Security Policy + } + + } + +You are now ready to implement your policy to decide whether the given permission is granted to the given Application. + +The `KF-Util module `_ provides ready-to-use implementations, described in the next sections. +Examples of integration are also available in the `Kernel-GREEN`_ project on GitHub. + +Security Manager with Application Declared Permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This Security Manager provides a ready-to-use implementation based on permissions declared by the Application itself. +It assumes the application and its permissions file have been approved beforehand by a moderator. + + +Principle +^^^^^^^^^ + +Basically, Applications embed a policy resource file that describes the permissions they need at runtime. +This file is then loaded when the Application is installed. +Finally, this Security Manager checks if the permission has been granted to the calling Application. +If a permission check is triggered but has not been declared, the Security Manager throws a `SecurityException`_. + +Here is a sequence diagram to describe the entire flow from Feature installation to uninstallation: + +.. image:: png/kernelSecurityPolicyManagerFlow.png + :align: center + + +Policy File Format +^^^^^^^^^^^^^^^^^^ + +An Application must define its Application policy file as a :ref:`resource `. +By default, the resource name must be ``/feature.policy.json``. + +The policy file format is described in JSON, which is the default syntax supported by this Security Manager. + +Before going further we strongly advise to take a look to the `java.security.Permission`_ specification and its class hierarchy to fully understand the way permissions work (name, action). + +The Application policy file declares the list of required `java.security.Permission`_ classes, names and actions as following: + +.. code-block:: json + + { + "permissions": { + "":{ + "":["",""], + "":[""] + }, + "":{ + "":[""] + } + } + } + +The permission ``name`` and ``action`` attributes are specific to the permission implementation. +Therefore each permission has its own definition of what a name is. + +The following keywords allow more flexibility over the content of the file: + +* the ``*`` (wildcard) symbol means "any". It can be used for permission class name, permission name and permission actions. +* the ``null`` keyword represents a Java ``null`` value. It can be used for permission name and permission actions. + +Policy File Example +^^^^^^^^^^^^^^^^^^^ + +Here is now an example of what a real JSON Application policy file can look like: + +.. code-block:: json + + { + "permissions": { + "ej.microui.display.DisplayPermission":{ + "*":[] + }, + "ej.microui.event.EventPermission":{ + "null":["null"] + }, + "ej.microui.display.FontPermission":{}, + "ej.microui.display.ImagePermission":{ + "null":["*"] + },"ej.microui.MicroUIPermission":{ + "*":["start"] + },"java.net.SocketPermission":{ + "www.microej.com":["connect","resolve"] + },"java.util.PropertyPermission":{ + "property":["write","read"] + },"java.lang.RuntimePermission":{ + "exit":[] + } + } + } + + +To simplify the file structure you can also choose to have an empty object value for permission class name or/and permission actions such as shown in the example above: + +.. code-block:: json + + { + "permissions": { + "ej.microui.display.DisplayPermission":{ + "*":[] + }, + "ej.microui.display.FontPermission":{}, + "java.lang.RuntimePermission":{ + "exit":[] + } + } + } + + +This example: + +* allows the usage of any permission name and any actions for the ``ej.microui.display.DisplayPermission`` permission. +* allows the usage of any permission name and any actions for the ``ej.microui.display.FontPermission`` permission. +* allows the ``exit`` permission name and any actions for the ``java.lang.RuntimePermission`` permission. + +Using an empty value or the ``*`` wildcard is left to the developer preference and should be processed in the exact same way by the security policy resource loader. + +Kernel Implementation +^^^^^^^^^^^^^^^^^^^^^ + +Here are the steps to integrate this Security Manager in your Kernel: + + +#. Add the dependency to the `KF-Util library `_ in the Kernel build file + + .. tabs:: + + .. tab:: Gradle (build.gradle.kts) + + .. code-block:: kotlin + + implementation("com.microej.library.util:kf-util:2.8.0") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + + +#. Make sure to embed `java.security.Permission`_ class names + + If the Kernel does not embed all class names (see :ref:`Stripping Class Names from an Application `), + the specified Permission class names must be embedded by declaring them as :ref:`Required Types `. + Any permission check done on a permission class without embedded name will result in a `SecurityException`_. + +#. Create the policy resource loader. By default, the library comes with a policy resource loader for the JSON format. + + .. code-block:: java + + SecurityPolicyResourceLoader loader = new JsonSecurityPolicyLoader(); + + You can also define your own format for the policy resource file by implementing the `_SecurityPolicyResourceLoader`` interface. + Optionally, you can change the Application file policy name, by setting the :ref:`System Property ` ``feature.policy.name`` (defaults to ``/feature.policy.json``). + +#. Create the `KernelSecurityPolicyManager`_ instance with the policy resource loader + + .. code-block:: java + + SecurityManager sm = new KernelSecurityPolicyManager(loader); + +#. Register this instance as the current Security Manager + + .. code-block:: java + + System.setSecurityManager(sm); + +.. note:: + To log every authorized access, change the logger level to ``FINE`` in the Kernel system properties such as + ``.level=FINE``. + + +Security Manager with Permission Dispatch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This Security Manager provides a template for dispatching the permission check per kind of `java.security.Permission`_ class. +The Kernel implementation must provide instances of `FeaturePermissionCheckDelegate`_ to specify the behavior of the `SecurityManager.checkPermission(Permission)`_ for each permission class. +If a permission check is done and no delegate for its permission is found, a `SecurityException`_ is thrown. +The policy grants all applications the permission for a list of permission classes and logs all protected accesses by Applications. + +Here are the steps to integrate this Security Manager in your Kernel: + +#. Add the dependency to the `KF-Util library `_ in the Kernel build file + + .. tabs:: + + .. tab:: Gradle (build.gradle.kts) + + .. code-block:: kotlin + + implementation("com.microej.library.util:kf-util:2.8.0") + + .. tab:: MMM (module.ivy) + + .. code-block:: xml + + + +#. Create the `KernelSecurityManager`_ instance + + .. code-block:: java + + KernelSecurityManager sm = new KernelSecurityManager(loader); + +#. Create a new class that implements the `FeaturePermissionCheckDelegate`_ interface like ``MySocketPermissionCheckDelegate`` below. + + .. code-block:: java + + public class CustomPermissionCheckDelegate implements FeaturePermissionCheckDelegate { + + @Override + public void checkPermission(Permission permission, Feature feature) { + SocketPermission sPerm = (SocketPermission)permission; + + // implement here the SocketPermission check for this Application + + } + + } + +#. Associate an instance of this `FeaturePermissionCheckDelegate`_ subclass with the `java.security.Permission`_ to be checked (like ``SocketPermission`` in the example below) by means of the Security Manager. + + .. code-block:: java + + sm.setFeaturePermissionDelegate(SocketPermission.class, new MySocketPermissionCheckDelegate()); + + This code will apply the logic inside of the ``MySocketPermissionCheckDelegate#checkPermission(Permission permission, Feature feature)`` method to all mapped permissions (such as ``SocketPermission.class`` for this specific example). + +#. Repeat the two previous steps for each supported `java.security.Permission`_ class. + +#. Register this instance as the current Security Manager + + .. code-block:: java + + System.setSecurityManager(sm); + +.. note:: + + The `Kernel-GREEN`_ uses this Security Manager template to log all the Permission checks on the standard output. + +.. _SecurityManager: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/SecurityManager.html +.. _SecurityManager.checkPermission(Permission): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/SecurityManager.html#checkPermission-java.security.Permission- +.. _System.setSecurityManager(SecurityManager): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/System.html#setSecurityManager-java.lang.SecurityManager- +.. _Kernel-GREEN: https://github.com/MicroEJ/Kernel-GREEN +.. _FeaturePermissionCheckDelegate: https://repository.microej.com/javadoc/microej_5.x/apis/com/microej/kf/util/security/FeaturePermissionCheckDelegate.html +.. _SecurityException: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/SecurityException.html +.. _FeaturePolicyPermission: https://repository.microej.com/javadoc/microej_5.x/apis/com/microej/kf/util/security/FeaturePolicyPermission.html +.. _SecurityPolicyResourceLoader: https://repository.microej.com/javadoc/microej_5.x/apis/com/microej/kf/util/security/SecurityPolicyResourceLoader.html +.. _java.security.Permission: https://repository.microej.com/javadoc/microej_5.x/apis/java/security/Permission.html +.. _com.microej.library.util.kf-util: https://repository.microej.com/javadoc/microej_5.x/apis/com/microej/kf/util/security/package-summary.html +.. _KernelSecurityManager: https://repository.microej.com/javadoc/microej_5.x/apis/com/microej/kf/util/security/KernelSecurityManager.html +.. _KernelSecurityPolicyManager: https://repository.microej.com/javadoc/microej_5.x/apis/com/microej/kf/util/security/KernelSecurityPolicyManager.html + + + +.. + | Copyright 2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. \ No newline at end of file diff --git a/KernelDeveloperGuide/featuresCommunication.rst b/KernelDeveloperGuide/featuresCommunication.rst index 12ce02ae2..a7399f2c4 100644 --- a/KernelDeveloperGuide/featuresCommunication.rst +++ b/KernelDeveloperGuide/featuresCommunication.rst @@ -252,7 +252,7 @@ Kernel Types Converter The Shared Interface mechanism allows to transfer an object instance of a Kernel type from one Feature to an other (see :ref:`section.transferable.types` section). -To do that, the Kernel must register a new Kernel type converter. +To do that, the Kernel must :ref:`register a new Kernel type converter `. See the `Converter`_ class and `Kernel.addConverter()`_ method for more details. The table below shows some converters defined in the `com.microej.library.util#kf-util`_ library. diff --git a/KernelDeveloperGuide/index.rst b/KernelDeveloperGuide/index.rst index 72aa2f2c0..1b5873282 100644 --- a/KernelDeveloperGuide/index.rst +++ b/KernelDeveloperGuide/index.rst @@ -14,6 +14,7 @@ Kernel Developer Guide runtimeEnvironment kernelUID sandboxedAppLifecycle + applicationSecurityPolicy featuresCommunication kfEnabledLibraries kfTestsuite diff --git a/KernelDeveloperGuide/kernelCreation.rst b/KernelDeveloperGuide/kernelCreation.rst index 669bb953d..720bfafd8 100644 --- a/KernelDeveloperGuide/kernelCreation.rst +++ b/KernelDeveloperGuide/kernelCreation.rst @@ -62,7 +62,7 @@ A Kernel must define the set of classes, methods and static fields all applicati According to the :ref:`Kernel and Features specification `, no API is open by default to Sandboxed Applications. -This can be done either by declaring :ref:`Kernel APIs ` or by definining a :ref:`Runtime Environment `. +This can be done either by declaring :ref:`Kernel APIs ` or by defining a :ref:`Runtime Environment `. The main difference is from the Application development point of view. In the first case, the Application project still declares standard module dependencies. @@ -81,49 +81,7 @@ A Kernel API or a Runtime Environment module is added as a dependency with the c Implement a Security Policy --------------------------- -The Kernel can restrict sensitive or possibly unsafe operations performed by Sandboxed Applications, thus defining a security policy. -Implementing a security policy is achieved by enabling support for Security Management system-wide and by registering to the Kernel a custom `SecurityManager`_ that will handle the `Permission`_ checks. - -.. note:: - - An API controlled by the Security Manager must be guarded by a :ref:`Permission check `. - The usual API documentation convention is to declare to throw a `SecurityException`_ with details about the requested Permission. - -Enable the Security Management -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For the sake of ROM footprint optimization, calls to Permission checks are disabled by default. -In order to activate this feature the :ref:`option_enable_security_manager` option must be set. - -Implement your Security Policy -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This can be achieved by subclassing the base `SecurityManager`_ class, overriding its `SecurityManager.checkPermission(Permission)`_ method, -and registering an instance of this class to the Kernel by a call to `System.setSecurityManager(SecurityManager)`_. - -.. code-block:: java - - // create a new Security Manager - SecurityManager sm = new SecurityManager() { - @Override - public void checkPermission(java.security.Permission perm) { - // here implement your Kernel Security Policy - }; - }; - // register the Security Manager - System.setSecurityManager(sm); - -Then you have to implement your own Security Policy. - -Implementation of a Security Policy is demonstrated in the `Kernel-GREEN`_ project. This Kernel implements a logging-only Security Policy using the utility class `FeaturePermissionCheckDelegate`_ that helps in implementing Permission checks in a Multi-Sandbox environment. - -.. _SecurityManager: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/SecurityManager.html -.. _SecurityManager.checkPermission(Permission): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/SecurityManager.html#checkPermission-java.security.Permission- -.. _System.setSecurityManager(SecurityManager): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/System.html#setSecurityManager-java.lang.SecurityManager- -.. _Kernel-GREEN: https://github.com/MicroEJ/Kernel-GREEN -.. _FeaturePermissionCheckDelegate: https://repository.microej.com/javadoc/microej_5.x/apis/com/microej/kf/util/security/FeaturePermissionCheckDelegate.html -.. _SecurityException: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/SecurityException.html -.. _Permission: https://repository.microej.com/javadoc/microej_5.x/apis/java/security/Permission.html +A complete section about how to setup a security policy is available in the :ref:`Application security policy ` page. .. _pre_installed_application_vd: diff --git a/KernelDeveloperGuide/kf.rst b/KernelDeveloperGuide/kf.rst index b2575066a..9cfcbc6d5 100644 --- a/KernelDeveloperGuide/kf.rst +++ b/KernelDeveloperGuide/kf.rst @@ -3,22 +3,1122 @@ Kernel & Features Specification =============================== -Multi-Sandboxing is based on the Kernel & Features specification (KF). -The fundamental concepts are introduced in the :ref:`Sandboxed Application chapter `. +Introduction +------------ -The following table provides links to the complete KF APIs & specification. +Multi-Sandboxing of Applications is based on Kernel & Features semantic (KF). + +This document defines the Kernel & Features specification (KF profile), a Trusted Execution +Environment (TEE) targeting virtual machines. + +Specification Summary +~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :widths: 10 30 + :header-rows: 1 - * - **Documentation** - - **Link** + * - Documentation + - Link * - Java APIs - https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/package-summary.html - * - Specification - - https://repository.microej.com/packages/ESR/ESR-SPE-0020-KF-1.4-H.pdf - * - Module - - https://repository.microej.com/modules/ej/api/kf/ + * - Latest Version + - 1.7.0 + * - Module Dependency + - .. tabs:: + + .. tab:: SDK 6 + + .. code-block:: java + + implementation("ej.api:kf:1.7.0") + + .. tab:: SDK 5 + + .. code-block:: xml + + + + +Comments +~~~~~~~~ + +Your comments about this specification are welcome. Please contact :ref:`our support team ` with "KF" as subject. + +Basic Concepts +~~~~~~~~~~~~~~ + +Kernel & Features semantic (KF) allows an application to be split into +multiple parts: + +- the main application, called the Kernel. + +- zero or more applications, called Features. + +The Kernel is mandatory. It is assumed to be reliable, trusted and +cannot be modified. If there is only one application (i.e. only one main +entry point that the system starts with) then this application is called +the Kernel. + +A Feature is an application “extension” managed by the Kernel. A Feature +is fully controlled by the Kernel: it can be installed (dynamically or +statically pre-installed), started, stopped and uninstalled at any time +independent of the system state (particularly, a Feature never depends +on another Feature to be stopped). A Feature is optional, potentially +not-trusted, maybe unreliable and can be executed without jeopardizing +the safety of the Kernel execution and other Features. + +Resources accesses (RAM, hardware peripherals, CPU time, …) are under +control of the Kernel. + +First Example +~~~~~~~~~~~~~ + +This simple example illustrates a log of a message called by a Kernel +and a Feature. The ``KernelExample`` class is the main Kernel entry point. +The ``FeatureExample`` class is a Feature entry point. The way these +classes are assigned to contexts and how the Feature is installed is not +described here. (the Feature is assumed to be installed before the +Kernel main method starts). + +Kernel class +^^^^^^^^^^^^ + +.. code-block:: java + :caption: Illustration 1: Kernel Hello World Example + + package ej.kf.example.helloworld; + + import ej.kf.Feature; + import ej.kf.Kernel; + + /** + * Defines a Kernel class. The Kernel entry point is the regular main method. + */ + public class KernelExample { + + public static void main(String[] args) throws Exception { + log("Hello World !"); + for (Feature f : Kernel.getAllLoadedFeatures()) { + f.start(); + } + } + + /** + * Log a message, prefixed with the name of the caller + */ + public static void log(String message) { + String name = Kernel.getContextOwner().getName(); + System.out.println('[' + name + "]: " + message); + } + + } + + +Feature class +^^^^^^^^^^^^^ + +.. code-block:: java + :caption: Illustration 2: Feature Hello World Example + + package ej.kf.example.helloworld; + + import ej.kf.FeatureEntryPoint; + + /** + * Defines a Feature class that implements {@link FeatureEntryPoint} interface. + */ + public class FeatureExample implements FeatureEntryPoint { + + @Override + public void start() { + KernelExample.log("Hello World !"); + } + + @Override + public void stop() { + } + + } + +Expected Output +^^^^^^^^^^^^^^^ + +.. code-block:: + + [KERNEL]: Hello World ! + [FEATURE]: Hello World ! + +Ownership Rules +--------------- + +At runtime, each type, object and thread execution context has an owner. +This section defines ownership transmission and propagation rules. + +Type +~~~~ + +The owner of a type is fixed when such type is loaded and that owner +cannot be modified after. + +The owner of an array-of-type type is the owner of the type. Array of +basetypes are lazily loaded. Those that are required by the Kernel are +owned by the Kernel. Other arrays are loaded in any Feature that require +them. + +The owner of a type can be retrieved by calling +`Kernel.getOwner()`_ with the `Class`_ instance. + +Object +~~~~~~ + +When an object is created, it is assigned to the owner of the execution +context owner. + +The owner of an object can be retrieved by calling +`Kernel.getOwner()`_ with the given object. + +Execution Context +~~~~~~~~~~~~~~~~~ + +When a thread is started, the first execution context is set to the +owner of the thread object. When a method is called from :ref:`Kernel mode ` +and its receiver is owned by a Feature, the +execution context is set to the owner of the receiver. In all other +cases, the execution context of the method called is the execution +context of the caller. + +The owner of the current execution context can be retrieved by calling +`Kernel.getContextOwner()`_. + +When a method returns, the execution context owner of the caller remains +the one it was before the call was done. + +The Kernel is the first application to run, and it is triggered by the +system when it boots. The Kernel starts in Kernel mode, creating a first +thread owned by the Kernel. + +The Kernel can execute a dynamic piece of code (`Runnable`_) in +a Feature context by calling `Kernel.runUnderContext()`_. + +.. _kernelmode: + +Kernel Mode +~~~~~~~~~~~ + +An execution context is said to be in *Kernel mode* when the current +execution context is owned by the Kernel. The method `Kernel.enter()`_ +sets the current execution context owner to the Kernel. The method +`Kernel.exit()`_ resets the current execution context owner to the one +when the method `Kernel.enter()`_ was called. + +Execution Rules +--------------- + +Notes: this specification does not force all rules to be checked at +runtime. When a rule is checked at runtime, a +`IllegalAccessError`_ must be thrown at the execution point where +the rule is broken. + +Type References +~~~~~~~~~~~~~~~ + +A type owned by the Kernel cannot refer to a type owned by a Feature. + +A type owned by a Feature can refer to a type owned by the Kernel if and +only if it has been exposed as an API type. + +A type owned by a Feature cannot refer to a type owned by another +Feature. + +All the types of the KF library (package ``ej.kf.*``) are owned by the +Kernel. A type owned by a Feature cannot access any types of this +library except the `FeatureEntryPoint`_ interface and the +`Proxy`_ class. + +Method References +~~~~~~~~~~~~~~~~~ + +A type owned by a Feature can refererence a method of type owned by the +Kernel if and only if it has been exposed as an API method. + +Field References +~~~~~~~~~~~~~~~~ + +Instance Field References +^^^^^^^^^^^^^^^^^^^^^^^^^ + +A type owned by a Feature can refer to all instance fields of a type +owned by the Kernel, if and only if the type has been exposed as an API +type and the field is accessible according to Java access control +rules. + +Static Field References +^^^^^^^^^^^^^^^^^^^^^^^ + +A type owned by a Feature can refer to a static field of a type owned by +the Kernel if and only if it has been exposed as an API static field. + +A static field of a type owned by a Feature cannot refer to an object +owned by another Feature. + +An object owned by a Feature can be assigned to a static field of a type +owned by the Kernel if and only if the current execution context is in +:ref:`Kernel mode `, otherwise a +`IllegalAccessError`_ is thrown at runtime. + +.. _contextlocalstorage: + +Context Local Static Field References +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, a static field holding an object reference is stored in a +single memory slot in the context of the owner of the type that defines +the field. + +The Kernel can declare a static field as a context local storage field +in ``kernel.intern`` file (See section :ref:`ctxtlocalstoragegrammar` for full format +specification). A memory slot is then allocated for the Kernel and +duplicated for each Feature. As it is a static field, it is initialized +to ``null``. + +.. code-block:: xml + :caption: Illustration 3: Context Local Storage Declaration of a Static Field + + + + + + +The Kernel can declare an optional initialization method. This method is +automatically invoked when the field is being read if its content is +``null``. This gives a hook to lazily initialize the static field before +its first read access. If the initialization method returns a ``null`` +reference, a `NullPointerException`_ is thrown. + +.. code-block:: xml + :caption: Illustration 4: Context Local Storage Declaration of a Static Field with an Initialization Method + + + + + + +Object References +~~~~~~~~~~~~~~~~~ + +An object owned by a Feature cannot be assigned to an object owned by +another Feature. + +An object owned by a Feature can be assigned to an object owned by the +Kernel if and only if the current execution context is in Kernel mode. + +Note that all possible object assignments are included (field +assignment, array assignment and array copies using +`System.arraycopy()`_). + +Local References +~~~~~~~~~~~~~~~~ + +An object owned by a Feature cannot be assigned into a local of an +execution context owned by another Feature. + +An object owned by a Feature can be assigned into a local of an +execution context owned by the Kernel. When leaving Kernel mode +explicitly with `Kernel.exit()`_, all locals that refer to an object +owned by another Feature are set to ``null``. + +Monitor Access +~~~~~~~~~~~~~~ + +A method owned by a Feature cannot synchronize on an object owned by the +Kernel. + +Native Method Declaration +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A class owned by a Feature cannot declare a ``native`` method. + +Reflective Operations +~~~~~~~~~~~~~~~~~~~~~ + +``Class.forName`` +^^^^^^^^^^^^^^^^^ + +The following table defines the extended rules for `Class.forName()`_ to throw a `ClassNotFoundException`_ when a type cannot be accessed. + +.. list-table:: Table 1: ``Class.forName(...)`` access rules + :header-rows: 1 + :widths: 2 2 2 6 + + - + - Context Owner + - Code Owner + - Type Owner + - ``Class.forName(Type)`` allowed + - + - ``K`` + - ``K`` + - ``K`` + - ``true`` + - + - ``K`` + - ``K`` + - ``F`` + - ``false`` + - + - ``K`` + - ``F`` + - ``K`` + - ``N/A`` + - + - ``K`` + - ``F`` + - ``F`` + - ``N/A`` + - + - ``F`` + - ``K`` + - ``K`` + - ``true`` + - + - ``Fi`` + - ``K`` + - ``Fj`` + - ``i==j`` + - + - ``F`` + - ``F`` + - ``K`` + - ``true`` if the type has been exposed as an :ref:`API type `, ``false`` otherwise. + - + - ``Fi`` + - ``Fi`` + - ``Fj`` + - ``i==j`` + + +``Class.newInstance`` +^^^^^^^^^^^^^^^^^^^^^ + +The following table defines the extended rules for `Class.newInstance()`_. + +.. list-table:: Table 2: ``Class.newInstance(...)`` access rules + :header-rows: 1 + + - + - Context Owner + - Code Owner + - Class Owner + - New instance owner + - + - ``K`` + - ``K`` + - ``K`` + - ``K`` + - + - ``K`` + - ``K`` + - ``F`` + - ``F`` + - + - ``K`` + - ``F`` + - ``K`` + - ``N/A`` + - + - ``K`` + - ``F`` + - ``F`` + - ``N/A`` + - + - ``F`` + - ``K`` + - ``K`` + - ``F`` + - + - ``F`` + - ``K`` + - ``F`` + - ``F`` + - + - ``F`` + - ``F`` + - ``K`` + - ``F`` + - + - ``F`` + - ``F`` + - ``F`` + - ``F`` + + +``Class.getResourceAsStream`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +defines the extended rules for +`Class.getResourceAsStream()`_ to return ``null`` when resource is not allowed to be accessed. + +.. list-table:: Table 3: ``Class.getResourceAsStream(...)`` access rules + :header-rows: 1 + :widths: 2 2 2 6 + + - + - Context owner + - Code owner + - Resource owner + - ``Class.getResourceAsStream(String)`` allowed + - + - ``K`` + - ``K`` + - ``K`` + - ``true`` + - + - ``K`` + - ``K`` + - ``F`` + - ``false`` + - + - ``K`` + - ``F`` + - ``K`` + - ``N/A`` + - + - ``K`` + - ``F`` + - ``F`` + - ``N/A`` + - + - ``F`` + - ``K`` + - ``K`` + - ``true`` + - + - ``Fi`` + - ``K`` + - ``Fj`` + - ``i==j`` + + If the same resource name is declared by both the Kernel and + the Feature, the Feature resource takes precedence over the + Kernel resource. + - + - ``F`` + - ``F`` + - ``K`` + - ``false`` + - + - ``Fi`` + - ``Fi`` + - ``Fj`` + - ``i==j`` + + +``Thread.currentThread`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Threads and their execution contexts have owners. The +``Thread.currentThread()`` method relates to the thread's owner that is +executing the current execution context only. There is no obligation +that two execution contexts that are in a caller-callee relationship +have the same (==) returned ``java.lang.Thread`` object when using +``Thread.currentThread()`` method. + +If the Thread that initiated the execution has the same owner as the +current execution context or if execution is in Kernel mode, then the +thread that initiates the execution is returned, otherwise, a +``java.lang.Thread`` object owned by the Kernel is returned. + +Feature Lifecycle +----------------- + +Entry point +~~~~~~~~~~~ + +Each Feature must define an implementation of the +`FeatureEntryPoint`_. `FeatureEntryPoint.start()`_ method is called +when the Feature is started. It is considered to be the main method of +the Feature application. `FeatureEntryPoint.stop()`_ method is called +when the Feature is stopped. It gives a chance to the Feature to +terminate properly. + +States +~~~~~~ + +A Feature is in one of the following states: + +- **INSTALLED**: Feature has been successfully linked to the Kernel and is not running. There are no references from the Kernel to objects owned by this Feature. + +- **STARTED**: Feature has been started and is running. + +- **STOPPED**: Feature has been stopped and all its owned threads and execution contexts are terminated. The memory and resources are not yet reclaimed. See section :ref:`stopsequence` for the complete stop sequence. + +- **UNINSTALLED**: Feature has been unlinked from the Kernel. + +The following illustration describes the Feature state diagram and the methods that changes Feature's state. + +.. _illustration-5: +.. figure:: png/kf_spec/kf_lifecycle.png + :align: center + :scale: 75% + + Illustration 5: Feature State Diagram + +Installation +~~~~~~~~~~~~ + +A Feature is installed by the Kernel using +`Kernel.install()`_. The content of the Feature data to be +loaded is implementation dependent. The Feature data is read and linked +to the Kernel. If the Feature cannot be linked to the Kernel, an +`IncompatibleFeatureException`_ is thrown. Otherwise, the Feature +is added to the list of loaded Features and its state is set to the +``INSTALLED`` state. + +Start +~~~~~ + +A Feature is started by the Kernel using `Feature.start()`_. The Feature +is switched in the ``STARTED`` state. A new thread owned by the Feature is +created and started. Next steps are executed by the newly created +thread: + +- Feature clinits are executed. + +- Entrypoint is instanciated. + +- `FeatureEntryPoint.start()`_ is called. + +.. _stopsequence: + +Stop +~~~~ + +A Feature is stopped explicitly by the Kernel using `Feature.stop()`_. +Features may be stopped implicitly by the Resource Control Manager. Next +steps are executed: + +- On explicit `Feature.stop()`_ call, a new thread owned by the Feature is created and `FeatureEntryPoint.stop()`_ is executed within this new thread. + +- Wait until this new thread is done, or until a global timeout stop-time occurred [1]_. + +- All execution contexts, from any thread, owned by the Feature are cleared, which implies that a `DeadFeatureException`_ is thrown in threads that are running the stopped Feature code or in threads that want to call stopped Feature code. + +- Wait until all threads owned by the Feature are terminated. + +- Native resources (files, sockets, …) opened by the Feature that remain opened after `FeatureEntryPoint.stop()`_ execution are closed abruptly. + +- The Feature state is set to the ``STOPPED`` state. + +- `FeatureStateListener.stateChanged()`_ is called for each registered listener. + +- Objects owned by the Feature are reclaimed. + +- If there are no remaining alive objects [2]_: + + - Feature state is set to the ``INSTALLED`` state. + + - `FeatureStateListener.stateChanged()`_ is called for each registered listener. + +The method `Feature.stop()`_ can be called several times, until the +Feature is set to the ``INSTALLED`` state. + +.. [1] + The default timeout stop-time is 2,000ms. + +.. [2] + If there are any remaining alive Feature objects after the Kernel listeners have been called, the Feature will stay in the ``STOPPED`` state indefinitely. + The Kernel has an issue. However, it can continue running and orchestrating other applications, but it cannot restart or uninstall the problematic Feature. + + +Uninstallation +~~~~~~~~~~~~~~ + +A Feature is uninstalled by the Kernel using `Kernel.uninstall()`_. The +Feature code is unlinked from the Kernel and reclaimed. The Feature is +removed from the list of loaded Features and its state is set to the +``UNINSTALLED`` state. The Feature does not exist anymore in the system. + +Class Spaces +------------ + +Overview +~~~~~~~~ + +.. _illustration-6: +.. figure:: png/kf_spec/classloader.png + :align: center + :scale: 75% + + Illustration 6: Kernel & Features Class Spaces Overview + + +Private Types +~~~~~~~~~~~~~ + +The Kernel and the Features define their own private name space. +Internal types are only accessible from within the Kernel or Features +that define these types. The Kernel or a Feature can have only one type +for a specific fully qualified name, insuring there are not two types in +the Kernel or in a Feature sharing the same fully qualified name. + +.. _kernel_api: + +Kernel API Types +~~~~~~~~~~~~~~~~ + +The Kernel can expose some of its types, methods and static fields as +API to Features. A file describes the list of the types, the methods and +the static fields that Features can refer to. + +Here is an example for exposing `System.out.println(String)`_ to a Feature: + +.. code-block:: xml + :caption: Illustration 7: Kernel API Example for exposing ``System.out.println`` + + + + + + + +Section :ref:`kernelapi` describes the Kernel API file format. + +Precedence Rules +~~~~~~~~~~~~~~~~ + +APIs exposed by the Kernel are publicly available for all Features: they +form the global name space. + +A Kernel API type (from the global name space) always takes precedence +over a Feature type with the same fully qualified name when a Feature is +loaded. An type exposed by the Kernel cannot be overloaded by a Feature. + +Resource Control Manager +------------------------ + +CPU Control: Quotas +~~~~~~~~~~~~~~~~~~~ + +A Kernel can assign an execution quota to a Feature using +`Feature.setExecutionQuota()`_. The quota is expressed in execution +units. + +Quotas account to the running current context owner. + +When a Feature has reached its execution quota, its execution is +suspended until all other Features have reached their execution quota. +When there are no threads owned by Features eligible to be scheduled, +the execution counter of all Features is reset. + +Setting a Feature execution quota to zero causes the Feature to be +suspended (the Feature is paused). + +RAM Control: Feature Criticality +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each Feature has a criticality level between `Feature.MIN_CRITICALITY`_ +and `Feature.MAX_CRITICALITY`_. When an execution context cannot allocate +new objects because a memory limit has been reached, Features shall be +stopped following next semantic: + +- Select the Feature with the lowest criticality. +- If the selected Feature has a criticality lower than the current + execution context owner criticality, then stop the selected Feature + and all the Features with the same criticality. +- If no memory is available, repeat these two previous steps in + sequence until there are no more Features to stop. + +If no memory is reclaimed, then an `OutOfMemoryError`_ is thrown. + +Time-out Control: Watchdog +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All method calls that are done from a Kernel mode to a Feature mode are +automatically executed under the control of a watchdog. + +The watchdog timeout is set according to the following rules: + +- use the watchdog timeout of the current execution context if it has + been set, +- else use the watchdog timeout of the current thread if it has been + set, +- else use the global system watchdog timeout. + +The global system watchdog timeout value is set to `Long.MAX_VALUE`_ at +system startup. + +When the watchdog timeout occurs the offending Feature is stopped. + +Native Resource Control: Security Manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Kernel is responsible for holding all the native calls. The Kernel +shall provide methods (API) that systematically check, using the +standard security manager, that the access to a native call is granted +to the specific Feature. + +When an object owned by a Feature is not allowed to access a native +resource, a specific exception shall be thrown. + +Any native resource opened by a Feature must be registered by the Kernel +and closed when the Feature is stopped. + +Communication Between Features +------------------------------ + +A Feature can communicate with another Feature using :ref:`Shared Interfaces `. +This section explains the execution semantics and advanced configuration from the Kernel's perspective. + +Method Binding +~~~~~~~~~~~~~~ + +A Feature can call a method owned by another Feature, provided: + +- Both Features own an interface in their class space with the same fully qualified name. + +- Both Features have declared such interface as a Shared Interface. + +- The source Feature has declared a Proxy class for its Shared Interface. + +- The target Feature has registered to the Kernel an instance of a class implementing its Shared Interface. + +- The source Feature has requested from the Kernel an instance of a class implementing its interface. + +- The Kernel has bound the source interface to the target instance and returned an instance to the source Feature, implementing its Shared Interface. + +- The source Feature calls a method declared in the Shared Interface using this instance as receiver. + +- A method with the exact descriptor exists in the target Feature interface. + +- The arguments given by the source Feature can be transferred to the target Feature. + +- The value returned by the target Feature can be transferred to the source Feature (if the method does not return ``void``). + +Section :ref:`sharedinterfacefileformat` describes the Shared Interface file format specification. + +Object Binding +~~~~~~~~~~~~~~ + +An object owned by a Feature can be bound to an object owned by +another Feature using the method `Kernel.bind()`_. + +- When the target type is owned by the Kernel, the object is converted using the most accurate :ref:`Kernel type converter `. + +- When the target type is owned by the Feature, it must be a Shared Interface. + In this case, an instance of its :ref:`Proxy class ` is returned. + +Object identity is maintained across Features, so the same proxy instance is returned. +If a Proxy is bound to the Feature that owns the reference, the original object is passed instead (Proxy unwrapping). + +.. note:: + + The Kernel can manually bind an object using the `Kernel.bind()`_ method. + +.. _kernelconverter: + +Kernel Type Converters +~~~~~~~~~~~~~~~~~~~~~~ + +By default, Feature instances of types owned by the Kernel cannot be +passed across a Shared Interface method invocation. + +The Kernel can register a converter for each allowed type, using +`Kernel.addConverter()`_. The converter must implement `Converter`_ +and can implement one of the following behaviors: + +- by wrapper: manually allocating a Proxy reference by calling `Kernel.newProxy()`_. + +- by copy: with the help of `Kernel.clone()`_. + +Configuration Files +------------------- + +Kernel and Features Declaration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A Kernel must provide a declaration file named ``kernel.kf``. A Feature +must provide a declaration file named ``[name].kf``. + +KF Declaration file is a Properties file. It must appear at the root of +any application classpath (directory or JAR file). Keys are described +hereafter: + +.. list-table:: Illustration 10: KF Definition File Properties Specification + :header-rows: 1 + :widths: 2 2 6 + + - + - Key + - Usage + - Description + - + - entryPoint + - Mandatory for Feature only. + - The fully qualified name of the class that implements + `FeatureEntryPoint`_ + - + - name + - Optional + - ``KERNEL`` by default for the Kernel, or the name of the file + without the ``.kf`` extension for Features. + - + - version + - Mandatory + - String version, that can retrieved using + `Module.getVersion()`_ + +.. _kernelapi: + +Kernel API Definition +~~~~~~~~~~~~~~~~~~~~~ + +By default, when building a Kernel, no types are exposed as API for +Features, except `FeatureEntryPoint`_. Kernel types, methods and +static fields allowed to be accessed by Features must be declared in one +or more ``kernel.api`` files. They must appear at the root of any +application classpath (directory or JAR file). Kernel API file is an XML +file, with the following schema: + +.. code-block:: xml + :caption: Illustration 11: Kernel API XML Schema + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.. list-table:: Illustration 12: Kernel API Tags Specification + :widths: 2 8 8 + :header-rows: 1 + + * - Tag + - Attributes + - Description + * - require + - + - The root element + * - field + - + - Static field declaration. Declaring a field as a Kernel API + automatically declares its type as a Kernel API. + * - name + - Fully qualified name on the form ``[type].[fieldName]`` + - + * - method + - + - Method or constructor declaration. Declaring a method or a + constructor as a Kernel API automatically declares its type as + a Kernel API + * - name + - Fully qualified name on the form + ``[type].[methodName]([typeArg1,...,typeArgN)typeReturned``. + Types are fully qualified names or one of a base type as + described by the Java language (``boolean``, ``byte``, ``char``, + ``short``, ``int``, ``long``, ``float``, ``double``) When declaring a + constructor, ``methodName`` is the single type name. When + declaring a void method or a constructor, ``typeReturned`` is + ``void`` + - + * - type + - + - Type declaration. Declaring a type as Kernel API automatically + declares all its super types (classes and interfaces) and the + default constructor (if any) as Kernel API. + * - name + - Fully qualified name on the form + ``[package].[package].[typeName]`` + - + + +Identification +~~~~~~~~~~~~~~ + +Kernel and Features identification is based on a `X509 certificate `_. +The 6 first fields defined by RFC 2253 (``CN``: commonName, ``L``: localityName, ``ST``: stateOrProvinceName, ``O``: organizationName, ``OU``: organizationalUnitName, ``C``: countryName) can be read by calling +``ej.kf.Module.getProvider().getValue(...)``. + +The certificate file must be configured as following: + +- placed beside the related ``[name].kf`` file. + +- named ``[name].cert``. + +- ``DER``-encoded and may be supplied in binary or printable (Base64) + encoding. If the certificate is provided in Base64 encoding, it + must be bounded at the beginning by ``-----BEGIN CERTIFICATE-----``, + and must be bounded at the end by ``-----END CERTIFICATE-----``.  + +.. _sharedinterfacefileformat: + +Shared Interface Declaration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A Shared Interface file is an XML file ending with the ``.si`` suffix with +the following format: + +.. code-block:: xml + :caption: Illustration 13: Shared Interface XML Schema Specification + + + + + + + + + + + + + + + + + + + +Kernel Advanced Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``The kernel.intern`` files is for Kernel advanced configurations such as +declaring :ref:`context local storage static fields `. It +must appear at the root of any application classpath (directory or JAR +file). + +.. code-block:: xml + :caption: Illustration 14: Kernel Intern Root XML Schema Specification + + + + + + + + + + + + +Context Local Storage Static Field Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _ctxtlocalstoragegrammar: + +XML Schema & Format +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: xml + :caption: Table 5: Context Local Storage XML Schema Specification + + + + + + + + + + + +Typical Example +^^^^^^^^^^^^^^^ + +The following illustration describes the definition of a context local +storage static field (``I``), which is duplicated in each context (Kernel +and Features): + +.. _illustration-15: +.. figure:: png/kf_spec/context_local_storage_slots.png + :align: center + :scale: 75% + + Illustration 15: Context Local Storage of Static Field Example + + +The following illustration describes a detailed sequence of method calls +with the expected behavior. + +.. _illustration-16: +.. figure:: png/kf_spec/context_local_storage_sequences.png + :align: center + :scale: 75% + + Illustration 16: Context Local Storage Example of Initialization Sequence + +.. _Class: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/Class.html +.. _ClassNotFoundException: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/ClassNotFoundException.html +.. _IllegalAccessError: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/IllegalAccessError.html +.. _IncompatibleFeatureException`: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/IncompatibleFeatureException.html +.. _NullPointerException: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/NullPointerException.html +.. _Runnable: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/Runnable.html +.. _FeatureEntryPoint: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/FeatureEntryPoint.html +.. _Converter: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Converter.html +.. _Proxy: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Proxy.html +.. _Class.forName(): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/Class.html#forName-java.lang.String- +.. _Class.getResourceAsStream(): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/Class.html#getResourceAsStream-java.lang.String- +.. _Class.newInstance(): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/Class.html#newInstance-- +.. _DeadFeatureException: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/DeadFeatureException.html +.. _IncompatibleFeatureException: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/IncompatibleFeatureException.html +.. _Feature.start(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Feature.html#start-- +.. _Feature.stop(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Feature.html#stop-- +.. _Module.getVersion(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Module.html#getVersion-- +.. _Feature.setExecutionQuota(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Module.html#setExecutionQuota-int- +.. _FeatureEntryPoint.start(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/FeatureEntryPoint.html#start-- +.. _FeatureEntryPoint.stop(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/FeatureEntryPoint.html#stop-- +.. _Feature.MAX_CRITICALITY: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Feature.html#MAX_CRITICALITY +.. _Feature.MIN_CRITICALITY: https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Feature.html#MIN_CRITICALITY +.. _FeatureStateListener.stateChanged(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/FeatureStateListener.html#stateChanged-ej.kf.Feature-ej.kf.Feature.State- +.. _Kernel.bind(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#bind-T-java.lang.Class-ej.kf.Feature- +.. _Kernel.addConverter() : https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#addConverter-ej.kf.Converter- +.. _Kernel.clone() : https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#clone-T-ej.kf.Module- +.. _Kernel.newProxy(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#newProxy-T-ej.kf.Module- +.. _Kernel.enter(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#enter-- +.. _Kernel.exit(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#exit-- +.. _Kernel.install(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#install-java.io.InputStream- +.. _Kernel.uninstall(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#uninstall-ej.kf.Feature- +.. _Kernel.getOwner(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#getOwner-java.lang.Object- +.. _Kernel.getContextOwner(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#getContextOwner-- +.. _Kernel.runUnderContext(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/kf/Kernel.html#runUnderContext-ej.kf.Module-java.lang.Runnable- +.. _Long.MAX_VALUE: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/Long.html#MAX_VALUE +.. _OutOfMemoryError: https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/OutOfMemoryError.html +.. _System.arraycopy(): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/System.html#arraycopy-java.lang.Object-int-java.lang.Object-int-int- +.. _System.out.println(String): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/System.html#out .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free diff --git a/KernelDeveloperGuide/png/classloader.png b/KernelDeveloperGuide/png/classloader.png deleted file mode 100644 index e7e076c00..000000000 Binary files a/KernelDeveloperGuide/png/classloader.png and /dev/null differ diff --git a/KernelDeveloperGuide/png/context_local_storage_sequences.png b/KernelDeveloperGuide/png/context_local_storage_sequences.png deleted file mode 100644 index 52ef10ea5..000000000 Binary files a/KernelDeveloperGuide/png/context_local_storage_sequences.png and /dev/null differ diff --git a/KernelDeveloperGuide/png/context_local_storage_slots.png b/KernelDeveloperGuide/png/context_local_storage_slots.png deleted file mode 100644 index bee188a1f..000000000 Binary files a/KernelDeveloperGuide/png/context_local_storage_slots.png and /dev/null differ diff --git a/KernelDeveloperGuide/png/kernelSecurityPolicyManagerFlow.png b/KernelDeveloperGuide/png/kernelSecurityPolicyManagerFlow.png new file mode 100644 index 000000000..5335bc76b Binary files /dev/null and b/KernelDeveloperGuide/png/kernelSecurityPolicyManagerFlow.png differ diff --git a/KernelDeveloperGuide/png/kf_lifecycle.png b/KernelDeveloperGuide/png/kf_lifecycle.png deleted file mode 100644 index ab56e3dda..000000000 Binary files a/KernelDeveloperGuide/png/kf_lifecycle.png and /dev/null differ diff --git a/KernelDeveloperGuide/png/kf_spec/classloader.png b/KernelDeveloperGuide/png/kf_spec/classloader.png new file mode 100644 index 000000000..1de6499ab Binary files /dev/null and b/KernelDeveloperGuide/png/kf_spec/classloader.png differ diff --git a/KernelDeveloperGuide/png/kf_spec/classloader.pptx b/KernelDeveloperGuide/png/kf_spec/classloader.pptx new file mode 100644 index 000000000..2bbf495ee Binary files /dev/null and b/KernelDeveloperGuide/png/kf_spec/classloader.pptx differ diff --git a/KernelDeveloperGuide/png/kf_spec/context_local_storage.pptx b/KernelDeveloperGuide/png/kf_spec/context_local_storage.pptx new file mode 100644 index 000000000..ff312980d Binary files /dev/null and b/KernelDeveloperGuide/png/kf_spec/context_local_storage.pptx differ diff --git a/KernelDeveloperGuide/png/kf_spec/context_local_storage_sequences.png b/KernelDeveloperGuide/png/kf_spec/context_local_storage_sequences.png new file mode 100644 index 000000000..3e801e210 Binary files /dev/null and b/KernelDeveloperGuide/png/kf_spec/context_local_storage_sequences.png differ diff --git a/KernelDeveloperGuide/png/kf_spec/context_local_storage_slots.png b/KernelDeveloperGuide/png/kf_spec/context_local_storage_slots.png new file mode 100644 index 000000000..5fe6473c5 Binary files /dev/null and b/KernelDeveloperGuide/png/kf_spec/context_local_storage_slots.png differ diff --git a/KernelDeveloperGuide/png/kf_spec/kf_lifecycle.png b/KernelDeveloperGuide/png/kf_spec/kf_lifecycle.png new file mode 100644 index 000000000..6bb90d576 Binary files /dev/null and b/KernelDeveloperGuide/png/kf_spec/kf_lifecycle.png differ diff --git a/KernelDeveloperGuide/pptx/KernelSecurityPolicyManagerFlow.pptx b/KernelDeveloperGuide/pptx/KernelSecurityPolicyManagerFlow.pptx new file mode 100644 index 000000000..956c25038 Binary files /dev/null and b/KernelDeveloperGuide/pptx/KernelSecurityPolicyManagerFlow.pptx differ diff --git a/KernelDeveloperGuide/runtimeEnvironment.rst b/KernelDeveloperGuide/runtimeEnvironment.rst index 233d65066..311e50819 100644 --- a/KernelDeveloperGuide/runtimeEnvironment.rst +++ b/KernelDeveloperGuide/runtimeEnvironment.rst @@ -30,14 +30,28 @@ The following figure shows the overall build flow: Create a new Runtime Environment Module --------------------------------------- -A Runtime Environment :ref:`module project ` is created with the ``runtime-api`` skeleton. +.. tabs:: -.. code:: xml + .. tab:: SDK 6 - - - - + A Runtime Environment :ref:`Gradle project ` is created with the ``com.microej.gradle.runtime-api`` plugin. + + .. code:: java + + plugins { + id("com.microej.gradle.runtime-api") version "0.18.0" + } + + .. tab:: SDK 5 + + A Runtime Environment :ref:`module project ` is created with the ``runtime-api`` skeleton. + + .. code:: xml + + + + + Kernel APIs as Dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -46,31 +60,54 @@ The Kernel APIs can be declared as dependencies of the module. For example, the following dependencies declare a Runtime Environment that aggregates all classes, methods and fields defined by ``EDC``, ``KF``, ``BON``, ``MicroUI`` Kernel APIs modules. -.. code:: xml +.. tabs:: + + .. tab:: SDK 6 + + .. code:: java + + dependencies { + implementation("com.microej.kernelapi:edc:1.2.0") + implementation("ej.api:edc:1.3.4") + implementation("com.microej.kernelapi:kf:2.1.0") + implementation("ej.api:kf:1.5.1") + implementation("com.microej.kernelapi:bon:1.4.0") + implementation("ej.api:bon:1.4.0") + implementation("com.microej.kernelapi:microui:3.5.0") + implementation("ej.api:microui:3.5.0") + } + + .. warning:: - - - - - - + Unlike SDK 5 (MMM), Kernel API dependencies are not transitively fetched with SDK 6. They must therefore be explicitly added. -The libraries modules are fetched transitively from the Kernel APIs dependencies. -For example, the dependency ``com.microej.kernelapi#edc;1.0.6`` fetches the library `ej.api#edc;1.2.3`_. + .. tab:: SDK 5 -It is also possible to force the version of the libraries to use by declaring them as direct dependencies. -This is typically used to get a latest version of the library with improvements such as Javadoc fixes or Null Analysis annotations. -In this example: + .. code:: xml -.. code:: xml + + + + + + + + The libraries modules are fetched transitively from the Kernel APIs dependencies. + For example, the dependency ``com.microej.kernelapi#edc;1.0.6`` fetches the library `ej.api#edc;1.2.3`_. - - + It is also possible to force the version of the libraries to use by declaring them as direct dependencies. + This is typically used to get a latest version of the library with improvements such as Javadoc fixes or Null Analysis annotations. + In this example: + + .. code:: xml + + + - - + + -The Runtime Environment uses the version ``1.3.4`` of the EDC library instead of the version ``1.2.3`` fetched transitively by the dependency ``com.microej.kernelapi#edc;1.0.6``. + The Runtime Environment uses the version ``1.3.4`` of the EDC library instead of the version ``1.2.3`` fetched transitively by the dependency ``com.microej.kernelapi#edc;1.0.6``. .. _ej.api#edc;1.2.3: https://repository.microej.com/modules/ej/api/edc/1.2.3/ @@ -142,9 +179,17 @@ Here is a list of known libraries using an Add-On Processor: Use a Runtime Environment in an Application ------------------------------------------- -The Runtime Environment dependency must be declared in the Application project as following:: +The Runtime Environment dependency must be declared in the Application project as following: + +.. tabs:: + + .. tab:: SDK 6 + + microejRuntimeApi("com.mycompany:myruntimeapi:1.0.0") + + .. tab:: SDK 5 - + .. note:: diff --git a/SDK6UserGuide/appendix/applicationWrapper.rst b/SDK6UserGuide/appendix/applicationWrapper.rst new file mode 100644 index 000000000..07040acb5 --- /dev/null +++ b/SDK6UserGuide/appendix/applicationWrapper.rst @@ -0,0 +1,73 @@ +.. _gradle_application_wrapper_chapter: + +Application Wrapper +=================== + +The unification of the Application EntryPoints allows to build and run an Application regardless of +the VEE provided by the user (a VEE Port or a Kernel). To ensure that an Application can run on different kinds of VEE, +a wrapper class is generated. For example, +if your Application EntryPoint is a class containing a ``public static void main(String[args])`` method: + +.. code:: java + + package com.mycompany; + + public class MyClass { + public static void main(String[] args) { + System.out.println("Hello World!"); + } + } + +A wrapper class implementing the ``ej.kf.FeatureEntryPoint`` interface is created: + +.. code:: java + + package com.mycompany; + + import ej.kf.FeatureEntryPoint; + + public class MyClassWrapper implements FeatureEntryPoint { + @Override + public void start() { + com.mycompany.MyClass.main(new String[0]); + } + + @Override + public void stop() { + } + } + +Then, the execution of the Application depends on the VEE provided in the ``build.gradle.kts`` file of your project: + +- If a VEE Port or a Mono-Sandbox Kernel has been provided, the ``MyClass`` main class of the Application is executed. +- If a Multi-Sandbox Kernel has been provided, the Application is executed as a Feature of the Kernel. + +In addition to the wrapper class, the following resource files are generated: + +- The Feature Definition Files (``feature.kf``, ``feature.cert``), if they do not already exist, to use your Application as a Sandboxed Application. +- The Kernel Definition Files (``kernel.kf``, ``kernel.cert``), if they do not already exist, to use your Application as a Kernel Application. + +Refer to the :ref:`kf-feature-definition` section for more information about Feature and Kernel Definition Files. + +If your Application requires advanced features, it is also possible to :ref:`use a FeatureEntryPoint class as Application EntryPoint `. +In that case the created wrapper class is a class containing a ``public static void main(String[args])`` method that calls the +``start()`` method of your Application EntryPoint class: + +.. code:: java + + package com.mycompany; + + public class MyClassWrapper { + public static void main(String[] args) { + new com.mycompany.MyClass.start(); + } + } + +and the Kernel and Feature Definition files are generated. + +.. + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/SDK6UserGuide/appendix/dependenciesConfigurations.rst b/SDK6UserGuide/appendix/dependenciesConfigurations.rst index 98dfbd093..905edeca2 100644 --- a/SDK6UserGuide/appendix/dependenciesConfigurations.rst +++ b/SDK6UserGuide/appendix/dependenciesConfigurations.rst @@ -14,7 +14,7 @@ This chapter describes all the dependency configurations added to your project b - `Java plugin `__ - `Java Library plugin `__ -The following diagrams show the dependency configurations. Use this legend to interpret the colors: +The following graph describes the dependency configurations. Use this legend to interpret the colors: - Green background : Dependencies can be declared against this configuration - Gray background : This configuration is for consumption by tasks only @@ -22,6 +22,12 @@ The following diagrams show the dependency configurations. Use this legend to in .. graphviz:: graphConfigurations.dot +The MicroEJ Gradle plugins also define dependency configurations for internal use: + + - ``antScriptLauncherClasspath``, used by the :ref:`sdk6_module_natures.tasks.buildVirtualDevice` task + - ``addonProcessorClasspath`` , used by the :ref:`sdk6_module_natures.tasks.adp` task + - ``jdtCompilerClasspath``, used by the :ref:`sdk6_module_natures.addon_lib` and :ref:`sdk6_module_natures.application` plugins + - ``wrapperClasspath``, used by the ``compileJava`` task Publication Variants -------------------- diff --git a/SDK6UserGuide/appendix/graphConfigurations.dot b/SDK6UserGuide/appendix/graphConfigurations.dot index f98e20c81..5770ce9fc 100644 --- a/SDK6UserGuide/appendix/graphConfigurations.dot +++ b/SDK6UserGuide/appendix/graphConfigurations.dot @@ -12,13 +12,14 @@ digraph mygraph { edge [fontname="Helvetica,Arial,sans-serif"] "microejVee" [fillcolor = "#41f753"] "microejApplication" [fillcolor = "#41f753"] + "microejTool" [fillcolor = "#41f753"] + "microejRuntimeApi" [fillcolor = "#41f753"] "microejApplicationClasspath" [fillcolor = "#b0d6d3"] "microejVeeClasspath" [fillcolor = "#b0d6d3"] "microejKernelExecutableClasspath" [fillcolor = "#b0d6d3"] "virtualDeviceToolClasspath" [fillcolor = "#b0d6d3"] - "addonProcessorClasspath" [fillcolor = "#b0d6d3"] - "jdtCompilerClasspath" [fillcolor = "#b0d6d3"] - "wrapperClasspath" [fillcolor = "#b0d6d3"] + "microejRuntimeApiClasspath" [fillcolor = "#b0d6d3"] + "microejRuntimeApiKernelClasspath" [fillcolor = "#b0d6d3"] "loadVee" -> "microejVeeClasspath" [ label="uses" ] "microejVeeClasspath" -> "microejVee" @@ -27,7 +28,11 @@ digraph mygraph { "buildVirtualDevice" -> "microejApplicationClasspath" [ label="uses" ] "buildVirtualDevice" -> "virtualDeviceToolClasspath" [ label="uses" ] "microejApplicationClasspath" -> "microejApplication" - "adp" -> "addonProcessorClasspath" [ label="uses" ] - "com.microej.gradle.java plugins" -> "jdtCompilerClasspath" [ label="uses" ] - "compileJava" -> "wrapperClasspath" [ label="uses" ] + "virtualDeviceToolClasspath" -> "microejTool" + "microejRuntimeApiClasspath" -> "microejRuntimeApi" + "microejRuntimeApiKernelClasspath" -> "microejRuntimeApi" + "com.microej.gradle.application" -> "microejRuntimeApiClasspath" [ label="uses" ] + "buildWPK" -> "microejRuntimeApiKernelClasspath" [ label="uses" ] + "buildApplicationObjectFile" -> "microejRuntimeApiKernelClasspath" [ label="uses" ] + "buildFeature" -> "microejRuntimeApiKernelClasspath" [ label="uses" ] } \ No newline at end of file diff --git a/SDK6UserGuide/appendix/index.rst b/SDK6UserGuide/appendix/index.rst index 01b80623d..f7fa51ba2 100644 --- a/SDK6UserGuide/appendix/index.rst +++ b/SDK6UserGuide/appendix/index.rst @@ -6,6 +6,7 @@ Appendices virtualDevice dependenciesConfigurations + applicationWrapper .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free diff --git a/SDK6UserGuide/buildExecutable.rst b/SDK6UserGuide/buildExecutable.rst index a55cbdf4b..f4639fdae 100644 --- a/SDK6UserGuide/buildExecutable.rst +++ b/SDK6UserGuide/buildExecutable.rst @@ -22,6 +22,13 @@ Once these prerequisites are fulfilled, the Executable can be built: :width: 30% :align: center + | + + .. warning:: + Android Studio does not allow to run multiple Gradle tasks in parallel. + If you still want to execute several Gradle tasks simultaneously, + you can launch them from a terminal with the Gradle Command Line Interface (CLI). + .. tab:: Eclipse By double-clicking on the ``buildExecutable`` task in the Gradle tasks view: @@ -30,6 +37,14 @@ Once these prerequisites are fulfilled, the Executable can be built: :width: 50% :align: center + .. tab:: Visual Studio Code + + By double-clicking on the ``buildExecutable`` task in the Gradle tasks view: + + .. image:: images/vscode-buildExecutable-gradle-project.png + :width: 25% + :align: center + .. tab:: Command Line Interface From the command line interface:: diff --git a/SDK6UserGuide/buildFeature.rst b/SDK6UserGuide/buildFeature.rst index 91a37968e..ca038fc62 100644 --- a/SDK6UserGuide/buildFeature.rst +++ b/SDK6UserGuide/buildFeature.rst @@ -22,6 +22,13 @@ Once these prerequisites are fulfilled, the Feature file can be built: :width: 30% :align: center + | + + .. warning:: + Android Studio does not allow to run multiple Gradle tasks in parallel. + If you still want to execute several Gradle tasks simultaneously, + you can launch them from a terminal with the Gradle Command Line Interface (CLI). + .. tab:: Eclipse By double-clicking on the ``buildFeature`` task in the Gradle tasks view: diff --git a/SDK6UserGuide/buildVirtualDevice.rst b/SDK6UserGuide/buildVirtualDevice.rst index 1d223da85..ab82a5188 100644 --- a/SDK6UserGuide/buildVirtualDevice.rst +++ b/SDK6UserGuide/buildVirtualDevice.rst @@ -25,7 +25,14 @@ Once these prerequisites are fulfilled, the Virtual Device can be built: .. image:: images/intellij-buildVirtualDevice-gradle-project.png :width: 30% :align: center - + + | + + .. warning:: + Android Studio does not allow to run multiple Gradle tasks in parallel. + If you still want to execute several Gradle tasks simultaneously, + you can launch them from a terminal with the Gradle Command Line Interface (CLI). + .. tab:: Eclipse By double-clicking on the ``buildVirtualDevice`` task in the Gradle tasks view: @@ -34,6 +41,14 @@ Once these prerequisites are fulfilled, the Virtual Device can be built: :width: 50% :align: center + .. tab:: Visual Studio Code + + By double-clicking on the ``buildVirtualDevice`` task in the Gradle tasks view: + + .. image:: images/vscode-buildVirtualDevice-gradle-project.png + :width: 25% + :align: center + .. tab:: Command Line Interface From the command line interface:: @@ -84,6 +99,33 @@ This can be done by declaring :ref:`Kernel APIs ` as a dependency in implementation("com.microej.kernelapi:edc:1.2.0") } +.. _sdk_6_buildVirtualDevice_add_runtime_api: + +Add a Runtime Environment in a Virtual Device +--------------------------------------------- + +When building a Virtual Device for a Kernel, the set of classes, methods and static fields allowed to be used +by all applications can be defined by declaring a :ref:`runtime_environment` as a dependency in the build file:: + + dependencies { + microejRuntimeApi("com.mycompany:myruntimeapi:1.0.0") + } + +The transitive dependencies of the Runtime Environment are then embedded in the Virtual Device. + +.. _sdk_6_buildVirtualDevice_add_tool: + +Add a Tool in a Virtual Device +------------------------------ + +When building a Virtual Device, it is possible to define additional MicroEJ Tools to install inside, +by adding a dependency with the ``microejTool`` configuration. For example, to install the :ref:`sdk6_localDeployTool` tool, +add the following dependency to the build file of the project:: + + dependencies { + microejTool("com.microej.tool.kernel:localdeploy-extension:1.0.0") + } + .. _sdk_6_skip_virtual_device_build: Skip Virtual Device Build by Default diff --git a/SDK6UserGuide/createProject.rst b/SDK6UserGuide/createProject.rst index 332f179ea..f606dd7e2 100644 --- a/SDK6UserGuide/createProject.rst +++ b/SDK6UserGuide/createProject.rst @@ -194,6 +194,10 @@ This chapter explains the different ways to create a new project. You can then learn :ref:`how to launch the build of the project `, or :ref:`how to run it on the Simulator ` in the case of an Application. + .. tab:: Visual Studio Code + + MicroEJ does not provide wizards in VS Code to create new MicroEJ projects. Refer to the Command Line Interface tab to see how to create a project from Gradle. + .. tab:: Command Line Interface The creation of a project can be done via the command line interface via the Gradle ``init`` task. @@ -252,6 +256,7 @@ Refer to the module type you want to build to configure your project: - :ref:`Add-On Library ` - :ref:`Mock ` - :ref:`J2SE Library ` +- :ref:`Runtime API ` .. _sdk_6_create_project_configure_application: @@ -262,7 +267,7 @@ Application Project - Add the ``com.microej.gradle.application`` plugin in the ``build.gradle.kts`` file:: plugins { - id("com.microej.gradle.application") version "0.16.0" + id("com.microej.gradle.application") version "0.18.0" } .. note:: @@ -286,7 +291,7 @@ Add-On Library Project - Add the ``com.microej.gradle.addon-library`` plugin in the build script:: plugins { - id("com.microej.gradle.addon-library") version "0.16.0" + id("com.microej.gradle.addon-library") version "0.18.0" } .. note:: @@ -302,7 +307,7 @@ Mock - Add the ``com.microej.gradle.mock`` plugin in the build script:: plugins { - id("com.microej.gradle.mock") version "0.16.0" + id("com.microej.gradle.mock") version "0.18.0" } .. note:: @@ -318,7 +323,23 @@ J2SE Library Project - Add the ``com.microej.gradle.j2se-library`` plugin in the build script:: plugins { - id("com.microej.gradle.j2se-library") version "0.16.0" + id("com.microej.gradle.j2se-library") version "0.18.0" + } + + .. note:: + The ``java`` plugin must not be added since it is automatically applied by the MicroEJ plugin. + +Refer to the page :ref:`sdk6_module_natures` for a complete list of the available MicroEJ natures and their corresponding plugins. + +.. _sdk_6_create_project_configure_runtime_api: + +Runtime API Project +~~~~~~~~~~~~~~~~~~~~ + +- Add the ``com.microej.gradle.runtime-api`` plugin in the build script:: + + plugins { + id("com.microej.gradle.runtime-api") version "0.18.0" } .. note:: @@ -422,13 +443,13 @@ This section explains the different ways to add a module to an existing project. - Add the MicroEJ plugin, depending on the module nature you want to build, for example for an Add-On Library:: plugins { - id("com.microej.gradle.addon-library") version "0.16.0" + id("com.microej.gradle.addon-library") version "0.18.0" } or for an Application:: plugins { - id("com.microej.gradle.application") version "0.16.0" + id("com.microej.gradle.application") version "0.18.0" } Refer to the page :ref:`sdk6_module_natures` for a complete list of the available MicroEJ natures and their corresponding plugins. diff --git a/SDK6UserGuide/gettingStarted.rst b/SDK6UserGuide/gettingStarted.rst index 51869c3bc..230ecf7d0 100644 --- a/SDK6UserGuide/gettingStarted.rst +++ b/SDK6UserGuide/gettingStarted.rst @@ -15,7 +15,7 @@ Before you get started, be sure to understand the fundamentals about `MICROEJ VE What you will do: -- Choose a starter kit +- Choose a starter kit in the tables below - Install MICROEJ SDK - Watch the Get Started Tutorial - Get Started with MICROEJ VEE @@ -37,12 +37,16 @@ What you will learn: VEE Ports for Evaluation ------------------------ -These VEE ports are ideal to evaluate MicroEJ's technology. They include the latest software components. +These VEE ports are ideal to evaluate MicroEJ's technology. They include the latest versions of MicroEJ software components as much as possible. +In case you cannot get hands on your desired starter kit, please contact us, we may help to find hardware for you. .. list-table:: :widths: 50 50 :header-rows: 0 + * - |logo_nxp| + - |image_imx93| + :ref:`i.MX 93 Evaluation Kit ` * - |logo_nxp| - |image_rt1170| :ref:`i.MX RT1170 Evaluation Kit ` @@ -50,10 +54,17 @@ These VEE ports are ideal to evaluate MicroEJ's technology. They include the lat - |image_stm32f7508| :ref:`STM32F7508-DK Evaluation Kit ` +.. toctree:: + :hidden: + + gettingStartedIMX93 + gettingStartedIMXRT1170 + gettingStartedSTM32F7508 + VEE Port Examples ----------------- -These VEE ports are provided as-is. They can include libraries that are not the latest version. +These VEE ports are provided as-is. They can include libraries that are not the latest version. Choose your VEE port by clicking on the links below. .. list-table:: :widths: 50 50 @@ -70,6 +81,7 @@ All VEE Port source code examples can be found at `GitHub `__ to understand the principles of our technology. + +Prerequisites +------------- + +.. note:: + + This Getting Started has been tested on Windows 10 & 11 with a WSL distribution Ubuntu 22.04. Also note that examples used in this Getting Started could depend on older tools and libraries. Most notably our dependency manager plugin (using `Gradle `_) could be an older version. + +This Getting Started is separated into two main parts. + +The first part consists in running a demo application on the Virtual Device. All you need is: + + +* An Internet connection to access Github repositories & :ref:`Module Repositories `. +* MICROEJ SDK 6 (installed during :ref:`Environment Setup `). + +The second part consists in running the same demo application on your device. For that, you will need: + +* An i.MX93 Evaluation Kit, available `here `__. + +* An HDMI display with touchscreen connected with an `IMX-MIPI-HDMI adapter `__. + + * This getting started has been tested with a `MageDok T080A `_. + +* A prebuild Yocto Linux image, with all necessary linux packages preinstalled. + +* A Yocto SDK, to cross compile an sample application. + +.. _sdk_6_getting_started_imx93_environment_setup: + +Environment Setup +----------------- + +To follow this Getting Started, you need to: + +* Install MICROEJ SDK 6. +* Get the Example-Java-Widget from Github. + +Install MICROEJ SDK 6 +^^^^^^^^^^^^^^^^^^^^^ + +Install MICROEJ SDK 6 by following the :ref:`sdk_6_install` instructions. +IntelliJ IDEA is used on this Getting Started, but feel free to use your favorite IDE. + +Get Example-Java-Widget +^^^^^^^^^^^^^^^^^^^^^^^ + +For this Getting Started, the :guilabel:`Example-Java-Widget` Application will be used. You can download it using the following command:: + + git clone -b 8.0.0 https://github.com/MicroEJ/Example-Java-Widget.git + +.. note:: + + If you don't have Git installed, you can download the source code directly from our `GitHub repository `__. + Then you can click on::guilabel:`Code > Download ZIP`. + +Set up the Application on your IDE +---------------------------------- + +Import the Project +^^^^^^^^^^^^^^^^^^ + +The first step is to import the :guilabel:`Example-Java-Widget` Application into your IDE: + +.. note:: + + If you are using an IDE other than IntelliJ IDEA, please have a look at :ref:`sdk_6_import_project` section. + + +* If you are in the Welcome Screen, click on the :guilabel:`Open` button. Otherwise, click either on :guilabel:`File` > :guilabel:`Open...` or on :guilabel:`File` > :guilabel:`New` > :guilabel:`Project From Existing Sources...`. +* Select the ``Example-Java-Widget`` directory located where you downloaded it and click on the :guilabel:`OK` button. + + .. figure:: images/gettingStarted/iMX93/getting-started-import-demo.png + :alt: Import demo application + :align: center + :scale: 70% + +* If you are asked to choose a project model, select :guilabel:`Gradle`. + + .. raw:: html + +
+ + + + + + + + + +
+ + + +
+ Fig 1. Project Model Selection when Opening in IntelliJ IDEA + + Fig 2. Project Model Selection when Importing in IntelliJ IDEA +
+
+ + .. |image1| image:: images/intellij-import-gradle-project-01.png + .. |image2| image:: images/intellij-import-gradle-project-02.png + +* Click on the :guilabel:`Create` button. + +The Gradle project should now be imported into IntelliJ IDEA. Your workspace contains the following projects: + + .. figure:: images/gettingStarted/iMX93/getting-started-project-view.png + :alt: Workspace view + :align: center + :scale: 70% + +Select the VEE Port +^^^^^^^^^^^^^^^^^^^ + +In the gradle build file ``build.gradle.kts``, replace the VEE dependency ``microejVEE`` with the i.MX93, like this: + +.. code-block:: + + dependencies { + microejVee("com.microej.veeport.imx93:VEEPort_eval:1.0.2") + } + +For more information about how to select a VEE Port please refer to the following section: :ref:`sdk_6_select_veeport`. + +.. _sdk_6_getting_started_imx93_eula: + +Accept the MICROEJ SDK EULA +--------------------------- + +You may have to accept the SDK EULA if you haven't already done so, please have a look at :ref:`sdk_6_eula_acceptation`. + +.. _sdk_6_getting_started_imx93_run_virtual_device: + +Run an Application on the Virtual Device +---------------------------------------- + +To execute the :guilabel:`Example-Java-Widget` Application on the Virtual Device, the SDK provides the Gradle :guilabel:`runOnSimulator` task. + +.. note:: + + If you are using another IDE than IntelliJ IDEA, please have a look at the :ref:`sdk_6_run_on_simulator` section. + +* Double-click on the :guilabel:`runOnSimulator` task in the Gradle tasks view. It may take a few seconds. + + .. figure:: images/gettingStarted/iMX93/getting-started-runOnSimulator.png + :alt: runOnSimulator task + :align: center + :scale: 70% + +The Virtual Device starts and executes the :guilabel:`Example-Java-Widget` application. + + .. figure:: images/gettingStarted/iMX93/getting-started-virtual-device.png + :alt: Virtual Device + :align: center + :scale: 70% + +.. figure:: images/gettingStarted/well-done-mascot.png + :alt: Well Done + :align: center + :scale: 70% + +Well done! +---------- + +Now you know how to run an application on a Virtual Device. + +If you want to learn how to run an application on your i.MX93 Evaluation Kit, you can continue this Getting Started: :ref:`Run an Application on i.MX93 Evaluation Kit `. + +Otherwise, learn how to :ref:`Modify the Java Application `. + +.. _sdk_6_getting_started_imx93_run_on_device: + +Run an Application on i.MX93 Evaluation Kit +------------------------------------------- + +To deploy :guilabel:`Example-Java-Widget` application on your board, you will have to: + +* Set up your environment (toolchain, hardware setup). +* Request a 30 days :ref:`Evaluation License ` and install an activation key. +* Build the Executable. +* Run the Executable on board. + +Environment Setup +^^^^^^^^^^^^^^^^^ + +This chapter takes approximately one hour and will take you through the steps to build a VEE Executable and set up the evaluation kit. + +Install the Yocto SDK +""""""""""""""""""""" + +The Executable is built using a Yocto SDK. It contains the following: + +* The C toolchain. +* The cross-compiled libraries. +* All the necessary headers (libc, but also the headers of the kernel and the libraries installed in the firmware rootfs). +* An environment setup script (to set $CC, $LD, $SDKSYSROOT variables). + +A prebuilt version of the Yocto SDK is available here: `Yocto SDK Installer for iMX93 `_ + +To install the Yocto SDK, use the following commands in WSL or Linux: + +.. code-block:: + + $ chmod +x oecore-x86_64-armv7at2hf-neon-vfpv4-toolchain-nodistro.0.sh + $ ./oecore-x86_64-armv7at2hf-neon-vfpv4-toolchain-nodistro.0.sh + MicroEJ: 32-bit userspace + 64-bit kernel SDK installer version nodistro.0 + ========================================================================== + Enter target directory for SDK (default: /usr/local/oecore-x86_64): + You are about to install the SDK to "/usr/local/oecore-x86_64". Proceed [Y/n]? Y + [sudo] password for xxxxx: + Extracting SDK.................................................................................done + Setting it up...done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /usr/local/oecore-x86_64/environment-setup-armv7at2hf-neon-vfpv4-oemllib32-linux-gnueabi + $ . /usr/local/oecore-x86_64/environment-setup-cortexa55-oe-linux + +The installation path can then be used to build the VEE Executable. + +Install Required Packages +""""""""""""""""""""""""" + +Some additionnal packages will be required in order to build an executable. Run the following command (either in Linux or WSL): + +.. code-block:: + + sudo apt-get update && sudo apt-get install dos2unix make + +Flash the image on an SD card +""""""""""""""""""""""""""""" + +The Linux image is available here: `Yocto WIC Image for iMX93 `_ + +For this getting started we use a Linux image flashed on an SD card. + +Linux ++++++ + +To flash the image on Linux, use the following command (assuming the SDCard device is /dev/mmcblk0): + +.. code-block:: + + bmaptool copy lib32-core-image-microej-microej-imx93.wic.gz /dev/mmcblk0 + +Windows ++++++++ + +To flash the image on Windows, do the following: + +* Install Rufus: https://rufus.ie/en/. +* Extract the ``.wic`` file from the archive ``lib32-core-image-microej-microej-imx93.wic.gz``. +* Select your SD card device in the list at the top (see example of configuration below). +* Select your ``.wic`` file by clicking on ``SELECT`` +* Finally click on ``START`` at the bottom and wait for the process to finish. + + .. figure:: images/gettingStarted/iMX93/getting-started-rufus.png + :alt: Rufus + :align: center + +Hardware Setup +"""""""""""""" + + .. figure:: images/gettingStarted/iMX93/getting-started-setup.png + :alt: Setup + :align: center + :scale: 70% + +To setup the hardware you will need to connect the following on the EVK: + +* A USB C cable for the power (provided with the EVK). +* A USB C cable for the serial port. +* A USB C cable for the touchscreen device. +* A RJ45 cable to access the network. +* An HDMI cable connected to the IMX-HDMI-MIPI adapter. + +The serial port is used to connect to a shell, it uses the following parameters: + +.. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 10 + + * - Baudrate + - Data bits + - Parity bits + - Stop bits + - Flow control + * - 115200 + - 8 + - None + - 1 + - XON/XOFF + +To connect to the shell enter the login ``root``. + +Configure boot +++++++++++++++ + +By default, the i.MX93 evaluation kit will boot from the eMMC. +To change the boot mode to micro SD, set the DIP switch ``BMODE`` to ``0010``. + +Insert the flashed SD card and boot the device. After a few seconds, the display will show the IMX93 Getting Started Welcome page. +If no display is attached, information such as device IP address and documentation link will also be printed in the logs. + +LVDS display support +++++++++++++++++++++ + +This Getting Started has been tested with an HDMI display with a 1280x720 resolution. +If you want to use the official display instead (the `DY1212W-4856 `_) +you will need to reconfigure the device tree: + +* Boot your i.MX93 Evaluation Kit. +* Stop the booting process to access the U-boot menu by pressing a key on the serial console. +* In the U-boot menu, run the following commands: + +.. code-block :: + + setenv fdtfile imx93-11x11-evk-boe-wxga-lvds-panel.dtb + saveenv + boot + +* After the boot has completed you can test the display with: ``modetest -M imx-drm -s 35@33:1280x800-60.03``. + +Congratulations! You have finished the setup of your environment. You are now ready to discover how to build and run a MicroEJ application. + +Build the Executable for i.MX93 Evaluation Kit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build the Executable of the :guilabel:`Example-Java-Widget` Application, the SDK provides the Gradle :guilabel:`buildExecutable` task. + +.. note:: + + If you are using an IDE other than IntelliJ IDEA, please have a look at the :ref:`sdk_6_build_executable` section. + Come back to this page if you need to activate an Evaluation License. + +* Before using this task, you will have to configure some environment variables that depend on the OS you are using. + + * To do so, right-click on ``buildExecutable`` then ``Modify Run Configuration...``. + * Fill in your variables in ``Environment variables``, each one separated by a semicolon (see screenshot): + + * If you changed the default Yocto SDK installation path, set the following environment variable + + * ``APP_SDK_INSTALL``: Path to the Yocto SDK (by default ``/usr/local/oecore-x86_64/``) + + * When using Windows with WSL, set the WSL distribution name, which you can get with the command :guilabel:`wsl --list` in Windows terminal + + * ``WSL_DISTRIBUTION_NAME``: Name of the WSL distribution if using Windows (by default ``Ubuntu``). + + .. figure:: images/gettingStarted/iMX93/getting-started-intellij-variables.png + :alt: IntelliJ variables + :align: center + :scale: 70% + +* Double-click on the :guilabel:`buildExecutable` task in the Gradle tasks view. +* The build stops with a failure. +* Go to the top project in the console view and scroll up to get the following error message: + + .. figure:: images/gettingStarted/iMXRT1170/getting-started-console-output-license-uid.png + :alt: Console Output License UID + :align: center + :scale: 70% + +* Copy the UID. It will be required to activate your Evaluation license. + +Request your Evaluation License: + +* You can request your Evaluation license by following the :ref:`evaluation_license_request_activation_key` instructions. You will be asked to fill in the machine UID you just copied. + +* When you have received your activation key by email, drop it in the license directory by following the :ref:`evaluation_license_install_license_key` instructions (drop the license key zip file to the ``~/.microej/licenses/`` directory). + +Now your Evaluation license is installed, you can relaunch your application build by double-clicking on the :guilabel:`buildExecutable` task in the Gradle tasks view. It may take some time. + +The gradle task deploys the Application in the BSP and then builds the BSP using Make. + +The :guilabel:`Example-Java-Widget` application is built and ready to be flashed on i.MX93 Evaluation Kit once the hardware setup is completed. + +Run the Application on the i.MX93 Evaluation Kit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To run the :guilabel:`Example-Java-Widget` Application on i.MX93 Evaluation Kit, the application provides the Gradle :guilabel:`runOnDevice` task. + +.. note:: + + If you are using another IDE than IntelliJ IDEA, please have a look at the :ref:`sdk_6_run_on_device` section. + +* Before using this task, you will have to configure the device IP Address in the environment variables. + + * To do so, right-click on ``runOnDevice`` then ``Modify Run Configuration...``. + * Fill in your variables in ``Environment variables``, each one separated by a semicolon: + + * ``SSH_USER=root`` + * ``SSH_HOSTNAME``: IP address of the i.MX93 Evaluation Kit. + * ``APP_SDK_INSTALL``: Path to the Yocto SDK (by default ``/usr/local/oecore-x86_64/``). + * ``WSL_DISTRIBUTION_NAME``: Name of the WSL distribution if using Windows (by default ``Ubuntu``). + +* Double-click on the :guilabel:`runOnDevice` task in the Gradle tasks view. It may take some time. + + .. figure:: images/gettingStarted/iMX93/getting-started-runOnDevice.png + :alt: runOnDevice task + :align: center + :scale: 70% + +Once the application is running, you should see the :guilabel:`Example-Java-Widget` on your board. + +.. _sdk_6_getting_started_imx93_modify_java_application: + +Modify the Java Application +--------------------------- + +With MicroEJ, it is easy to modify and test your Java application on the Virtual Device. + +For example, we can modify the color of the items in the main page list. + +* Open :guilabel:`MainPage.java` located in the :guilabel:`src/main/java/com/microej/demo/widget/main/MainPage.java` folder +* Odd items background color is set line 74, replace the following line: + +.. code-block:: + + style.setBackground(new GoToBackground(GRAY)); + +with + +.. code-block:: + + style.setBackground(new GoToBackground(Colors.CYAN)); + +* Follow :ref:`sdk_6_getting_started_imx93_run_virtual_device` instructions to launch the modified application on the Virtual Device. + + + .. figure:: images/gettingStarted/iMX93/getting-started-runOnSimulator-modified.png + :alt: runOnDevice task + :align: center + :scale: 70% + +Going Further +------------- + +You have now successfully executed a MicroEJ application on an embedded device so what's next? + +If you are an application developer you can continue to explore MicroEJ's API and functionalities by running and studying our samples at GitHub: + +.. list-table:: + :widths: 33 33 33 + + * - Foundation Libraries + - Eclasspath + - IoT + * - This project gathers all the basic examples of the foundation libraries. + - This project gather all the examples of eclasspath. + - This project gathers simple applications using net libraries. + * - https://github.com/MicroEJ/Example-Foundation-Libraries + - https://github.com/MicroEJ/Example-Eclasspath + - https://github.com/MicroEJ/Example-IOT + +You can also learn how to build bigger and better applications by reading our :ref:`Application Developer Guide `. + +If you are an embedded engineer you could look at our VEE port examples at `GitHub `_. And to learn how create custom VEE ports you can read our :ref:`VEE Porting Guide `. + +You can also follow the :ref:`Kernel Developer Guide ` for more information on our multi-applications framework or read about our powerful wearable solution called :ref:`VEE Wear `. + +Last but not least you can choose to learn about specific topics by following one of our many :ref:`tutorials ` ranging from how to easily debug application to setting up a Continuous Integration process and a lot of things in between. + +.. + | Copyright 2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/SDK6UserGuide/gettingStartedIMXRT1170.rst b/SDK6UserGuide/gettingStartedIMXRT1170.rst index d470ff9f7..17e11b9c0 100644 --- a/SDK6UserGuide/gettingStartedIMXRT1170.rst +++ b/SDK6UserGuide/gettingStartedIMXRT1170.rst @@ -15,7 +15,7 @@ Prerequisites .. note:: - This Getting Started has been tested on Windows 10 & 11. + This Getting Started has been tested on Windows 10 & 11. Also note that examples used in this Getting Started could depend on older tools and libraries. Most notably our dependency manager plugin (using `Gradle `_) could be an older version. This Getting Started is separated in two main parts. @@ -27,7 +27,7 @@ The first part consists of running a demo application on the Virtual Device. All The second part consists of running the same demo application on your device. For that you will need: -* i.MX RT1170 Evaluation Kit, available `here `__. +* i.MX RT1170 Evaluation Kit, available `here `__. * RK055HDMIPI4MA0 display panel, available `here `__. * A GNU ARM Embedded Toolchain, Cmake and Make are needed to build the BSP. You will be guided on how to install the toolchain later. * LinkServer tool to flash the board. You will be guided on how to install this tool later. @@ -408,6 +408,34 @@ Here is the modified application running in simulation: :align: center :scale: 70% +Going Further +------------- + +You have now successfully executed a MicroEJ application on an embedded device so what's next? + +If you are an application developer you can continue to explore MicroEJ's API and functionalities by running and studying our samples at GitHub: + +.. list-table:: + :widths: 33 33 33 + + * - Foundation Libraries + - Eclasspath + - IoT + * - This project gathers all the basic examples of the foundation libraries. + - This project gather all the examples of eclasspath. + - This project gathers simple applications using net libraries. + * - https://github.com/MicroEJ/Example-Foundation-Libraries + - https://github.com/MicroEJ/Example-Eclasspath + - https://github.com/MicroEJ/Example-IOT + +You can also learn how to build bigger and better applications by reading our :ref:`Application Developer Guide `. + +If you are an embedded engineer you could look at our VEE port examples at `GitHub `_. And to learn how create custom VEE ports you can read our :ref:`VEE Porting Guide `. + +You can also follow the :ref:`Kernel Developer Guide ` for more information on our multi-applications framework or read about our powerful wearable solution called :ref:`VEE Wear `. + +Last but not least you can choose to learn about specific topics by following one of our many :ref:`tutorials ` ranging from how to easily debug application to setting up a Continuous Integration process and a lot of things in between. + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDK6UserGuide/gettingStartedIMXRT595.rst b/SDK6UserGuide/gettingStartedIMXRT595.rst index e209300cb..a9a80aa5e 100644 --- a/SDK6UserGuide/gettingStartedIMXRT595.rst +++ b/SDK6UserGuide/gettingStartedIMXRT595.rst @@ -15,7 +15,7 @@ Prerequisites .. note:: - This Getting Started has been tested on Windows 10 & 11. + This Getting Started has been tested on Windows 10 & 11. Also note that examples used in this Getting Started could depend on older tools and libraries. Most notably our dependency manager plugin (using `Gradle `_) could be an older version. This Getting Started is separated in two main parts. @@ -327,6 +327,20 @@ Now your Evaluation license is installed, you can relaunch your application buil The gradle task deploys the MicroEJ application in the BSP and then builds the BSP using Make. +.. warning:: + + On Windows, the build may fail because of file path length limit exceeded with following error message: + + .. code-block:: + + arm-none-eabi-gcc.exe: fatal error: no input Files + + In this case, shorten the build directory path in ``./watch-vg/build.gradle.kts``: + + .. code-block:: kotlin + + buildDir = file("C:/Demo-Wearable-VG/build") + The :guilabel:`Demo-Wearable-VG` application is built and ready to be flashed on i.MX RT595 Evaluation Kit once the hardware setup is completed. Flash the Application on the i.MX RT595 Evaluation Kit @@ -405,6 +419,34 @@ Here is the modified application running in simulation: :align: center :scale: 70% +Going Further +------------- + +You have now successfully executed a MicroEJ application on an embedded device so what's next? + +If you are an application developer you can continue to explore MicroEJ's API and functionalities by running and studying our samples at GitHub: + +.. list-table:: + :widths: 33 33 33 + + * - Foundation Libraries + - Eclasspath + - IoT + * - This project gathers all the basic examples of the foundation libraries. + - This project gather all the examples of eclasspath. + - This project gathers simple applications using net libraries. + * - https://github.com/MicroEJ/Example-Foundation-Libraries + - https://github.com/MicroEJ/Example-Eclasspath + - https://github.com/MicroEJ/Example-IOT + +You can also learn how to build bigger and better applications by reading our :ref:`Application Developer Guide `. + +If you are an embedded engineer you could look at our VEE port examples at `GitHub `_. And to learn how create custom VEE ports you can read our :ref:`VEE Porting Guide `. + +You can also follow the :ref:`Kernel Developer Guide ` for more information on our multi-applications framework or read about our powerful wearable solution called :ref:`VEE Wear `. + +Last but not least you can choose to learn about specific topics by following one of our many :ref:`tutorials ` ranging from how to easily debug application to setting up a Continuous Integration process and a lot of things in between. + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDK6UserGuide/gettingStartedSTM32F7508.rst b/SDK6UserGuide/gettingStartedSTM32F7508.rst index 5ab4546d4..044cce935 100644 --- a/SDK6UserGuide/gettingStartedSTM32F7508.rst +++ b/SDK6UserGuide/gettingStartedSTM32F7508.rst @@ -15,7 +15,7 @@ Prerequisites .. note:: - This Getting Started has been tested on Windows 10. + This Getting Started has been tested on Windows 10. Also note that examples used in this Getting Started could depend on older tools and libraries. Most notably our dependency manager plugin (using `Gradle `_) could be an older version. This Getting Started is separated in two main parts. @@ -283,6 +283,34 @@ Here is the modified application running in simulation: :align: center :scale: 70% +Going Further +------------- + +You have now successfully executed a MicroEJ application on an embedded device so what's next? + +If you are an application developer you can continue to explore MicroEJ's API and functionalities by running and studying our samples at GitHub: + +.. list-table:: + :widths: 33 33 33 + + * - Foundation Libraries + - Eclasspath + - IoT + * - This project gathers all the basic examples of the foundation libraries. + - This project gather all the examples of eclasspath. + - This project gathers simple applications using net libraries. + * - https://github.com/MicroEJ/Example-Foundation-Libraries + - https://github.com/MicroEJ/Example-Eclasspath + - https://github.com/MicroEJ/Example-IOT + +You can also learn how to build bigger and better applications by reading our :ref:`Application Developer Guide `. + +If you are an embedded engineer you could look at our VEE port examples at `GitHub `_. And to learn how create custom VEE ports you can read our :ref:`VEE Porting Guide `. + +You can also follow the :ref:`Kernel Developer Guide ` for more information on our multi-applications framework or read about our powerful wearable solution called :ref:`VEE Wear `. + +Last but not least you can choose to learn about specific topics by following one of our many :ref:`tutorials ` ranging from how to easily debug application to setting up a Continuous Integration process and a lot of things in between. + .. | Copyright 2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDK6UserGuide/graphAddonLibraryModule.dot b/SDK6UserGuide/graphAddonLibraryModule.dot index 25b8a7546..636e536f5 100644 --- a/SDK6UserGuide/graphAddonLibraryModule.dot +++ b/SDK6UserGuide/graphAddonLibraryModule.dot @@ -13,17 +13,15 @@ digraph mygraph { "adp" [fillcolor = "#f76241"] "checkModule" [fillcolor = "#f76241"] "loadVee" [fillcolor = "#f76241"] - "loadApplicationConfiguration" [fillcolor = "#f76241"] - "loadTestApplicationConfiguration" [fillcolor = "#f76241"] "runOnSimulator" [fillcolor = "#f76241"] + "execTool" [fillcolor = "#f76241"] "build" -> "check" "check" -> "test" "test" -> "classes" "test" -> "testClasses" - "test" -> "loadTestApplicationConfiguration" + "test" -> "loadVee" "testClasses" -> "compileTestJava" "testClasses" -> "processTestResources" - "loadTestApplicationConfiguration" -> "loadVee" "processResources" -> "adp" "processTestResources" -> "adp" "processTestResources" -> "classes" @@ -36,10 +34,10 @@ digraph mygraph { "uploadArchives" -> "jar" "jar" -> "classes" "runOnSimulator" -> "classes" - "runOnSimulator" -> "loadApplicationConfiguration" - "loadApplicationConfiguration" -> "loadVee" + "runOnSimulator" -> "loadVee" "checkModule" -> "assemble" "check" -> "checkModule" + "execTool" -> "loadVee" subgraph cluster_legend { label="Legend"; diff --git a/SDK6UserGuide/graphApplicationModule.dot b/SDK6UserGuide/graphApplicationModule.dot index a65bb2d7d..ef0a220ee 100644 --- a/SDK6UserGuide/graphApplicationModule.dot +++ b/SDK6UserGuide/graphApplicationModule.dot @@ -14,26 +14,23 @@ digraph mygraph { "checkModule" [fillcolor = "#f76241"] "loadKernelExecutable" [fillcolor = "#f76241"] "loadVee" [fillcolor = "#f76241"] - "loadApplicationConfiguration" [fillcolor = "#f76241"] - "loadExecutableConfiguration" [fillcolor = "#f76241"] - "loadFeatureConfiguration" [fillcolor = "#f76241"] - "loadTestApplicationConfiguration" [fillcolor = "#f76241"] "runOnSimulator" [fillcolor = "#f76241"] "buildWPK" [fillcolor = "#f76241"] + "buildApplicationObjectFile" [fillcolor = "#f76241"] "buildExecutable" [fillcolor = "#f76241"] "buildVirtualDevice" [fillcolor = "#f76241"] "buildFeature" [fillcolor = "#f76241"] "runOnDevice" [fillcolor = "#f76241"] "execTool" [fillcolor = "#f76241"] + "generateApplicationWrapper" [fillcolor = "#f76241"] "compileWrapperJava" [fillcolor = "#f76241"] "build" -> "check" "check" -> "test" "test" -> "classes" "test" -> "testClasses" - "test" -> "loadTestApplicationConfiguration" + "test" -> "loadVee" "testClasses" -> "compileTestJava" "testClasses" -> "processTestResources" - "loadTestApplicationConfiguration" -> "loadVee" "processResources" -> "adp" "processTestResources" -> "adp" "processTestResources" -> "classes" @@ -47,24 +44,22 @@ digraph mygraph { "uploadArchives" -> "jar" "jar" -> "classes" "runOnSimulator" -> "classes" - "runOnSimulator" -> "loadApplicationConfiguration" - "loadApplicationConfiguration" -> "loadVee" + "runOnSimulator" -> "loadVee" "checkModule" -> "assemble" "check" -> "checkModule" "buildWPK" -> "jar" "buildWPK" -> "javadoc" - "buildExecutable" -> "test" - "buildExecutable" -> "loadExecutableConfiguration" - "loadExecutableConfiguration" -> "loadVee" + "buildApplicationObjectFile" -> "loadVee" + "buildExecutable" -> "buildApplicationObjectFile" + "buildExecutable" -> "loadVee" "buildVirtualDevice" -> "loadVee" "buildVirtualDevice" -> "buildWPK" - "buildFeature" -> "loadFeatureConfiguration" - "loadFeatureConfiguration" -> "loadKernelExecutable" - "loadFeatureConfiguration" -> "loadVee" + "buildFeature" -> "loadVee" + "buildFeature" -> "loadKernelExecutable" "runOnDevice" -> "buildExecutable" - "execTool" -> "loadApplicationConfiguration" "execTool" -> "loadVee" - "compileWrapperJava" -> "compileJava" + "generateApplicationWrapper" -> "compileJava" + "compileWrapperJava" -> "generateApplicationWrapper" subgraph cluster_legend { label="Legend"; diff --git a/SDK6UserGuide/graphRuntimeApiModule.dot b/SDK6UserGuide/graphRuntimeApiModule.dot new file mode 100644 index 000000000..9e95eddca --- /dev/null +++ b/SDK6UserGuide/graphRuntimeApiModule.dot @@ -0,0 +1,47 @@ +digraph mygraph { + rankdir="RL"; + bgcolor="transparent" + fontname="Helvetica,Arial,sans-serif" + node [ + shape = box + width = 1.5 + color = "#7dc5dc" + style = filled + fontname="Helvetica,Arial,sans-serif" + ] + edge [fontname="Helvetica,Arial,sans-serif"] + "checkModule" [fillcolor = "#f76241"] + "buildRuntimeApiJar" [fillcolor = "#f76241"] + "compileRuntimeApi" [fillcolor = "#f76241"] + "shrinkRuntimeApi" [fillcolor = "#f76241"] + "build" -> "check" + "check" -> "test" + "test" -> "classes" + "test" -> "testClasses" + "testClasses" -> "compileTestJava" + "testClasses" -> "processTestResources" + "processTestResources" -> "classes" + "compileTestJava" -> "classes" + "javadoc" -> "classes" + "classes" -> "compileJava" + "classes" -> "processResources" + "build" -> "assemble" + "assemble" -> "jar" + "uploadArchives" -> "jar" + "jar" -> "classes" + "checkModule" -> "assemble" + "javadoc" -> "shrinkRuntimeApi" + "sourcesJar" -> "shrinkRuntimeApi" + "compileRuntimeApi" -> "shrinkRuntimeApi" + "jar" -> "compileRuntimeApi" + "buildRuntimeApiJar" -> "compileRuntimeApi" + "build" -> "buildRuntimeApiJar" + + subgraph cluster_legend { + label="Legend"; + microej [fillcolor="#f76241" label="MicroEJ task"]; + java [fillcolor="#7dc5dc" label="Java plugin or Base plugin task"]; + microej -> java [style=invis]; + java -> microej [style=invis]; + } +} \ No newline at end of file diff --git a/SDK6UserGuide/heapAnalyzer.rst b/SDK6UserGuide/heapAnalyzer.rst index 0d79e6af3..238ac96e2 100644 --- a/SDK6UserGuide/heapAnalyzer.rst +++ b/SDK6UserGuide/heapAnalyzer.rst @@ -90,8 +90,12 @@ In order to generate a Heap dump of an Application running on the Simulator: - Update your Application code to call the `System.gc()`_ method where you need a Heap dump. - run the Application on the Simulator. -When the `System.gc()`_ method is called, -a ``.heap`` file is generated in the ``build/output/application/heapDump/`` folder of the Application project. +When the `System.gc()`_ method is called: + +- if it is called from the Application, the ``.heap`` file is generated in the ``build/output//heapDump/`` folder of the project, + where ```` is the Fully Qualified Name of the Application Main class, for example (``com.mycompany.Main``). +- if it is called from a test class, the ``.heap`` file is generated in the ``build/testsuite/output//bin//heapDump/`` folder of the project, + where ```` is the Fully Qualified Name of the generated Main class and ```` is the date of the test execution, for example (``build/testsuite/output/20240625-1605-24/bin/com.mycompany._AllTests_MyTest/heapDump/``). Device ^^^^^^ @@ -161,6 +165,32 @@ If you are in a Multi-Sandbox context, the following sections must be dumped add - either dump the entire memory where microej runtime and code sections are linked, - or generate the :ref:`VEE memory dump script ` which will dump all the required sections instead. + .. note:: + + In a Mono-Sandbox context, use ``1_java_heap.hex``. + + In a Multi-Sandbox context, merge (at least) ``1_java_heap.hex`` and ``9_installed_features.hex`` with: + + .. tabs:: + + .. tab:: Command Prompt + + .. code-block:: bat + + copy /b 1_java_heap.hex + 9_installed_features.hex memory.hex + + .. tab:: PowerShell + + .. code-block:: powershell + + Get-Content 1_java_heap.hex, 9_installed_features.hex | Set-Content memory.hex + + .. tab:: Bash + + .. code-block:: bash + + cat 1_java_heap.hex 9_installed_features.hex > memory.hex + .. _sdk6_heapdumper_extract_heap: Extract the Heap dump from the ``.hex`` file diff --git a/SDK6UserGuide/howtos/buildExecutableWithMultipleVeePorts.rst b/SDK6UserGuide/howtos/buildExecutableWithMultipleVeePorts.rst index 14e0298c8..d5d3ac307 100644 --- a/SDK6UserGuide/howtos/buildExecutableWithMultipleVeePorts.rst +++ b/SDK6UserGuide/howtos/buildExecutableWithMultipleVeePorts.rst @@ -41,7 +41,7 @@ For example, if you want to build an Executable for two VEE Ports, you can creat for example:: plugins { - id("com.microej.gradle.application") version "0.16.0" apply false + id("com.microej.gradle.application") version "0.18.0" apply false } subprojects { diff --git a/SDK6UserGuide/howtos/disableIvyDescriptorPublication.rst b/SDK6UserGuide/howtos/disableIvyDescriptorPublication.rst new file mode 100644 index 000000000..d04d59ad1 --- /dev/null +++ b/SDK6UserGuide/howtos/disableIvyDescriptorPublication.rst @@ -0,0 +1,36 @@ +.. _sdk_6_disable_ivy_descriptor_publication: + +How To Disable Ivy Descriptor Publication +========================================= + +By default, SDK 6 adds an Ivy descriptor file to published artifacts in order for SDK 5 projects to be able to consume the module (e.g. an application built with SDK 5 depending on a library published with SDK 6). + + + +Disable Ivy Descriptor Publication by Default +--------------------------------------------- + +If you don't need SDK 5 backward compatibility, you can disable Ivy descriptor publication by setting the Gradle property ``enable.ivy.descriptor.default=false``. + +This property can be set in a ``gradle.properties`` file in ``/.gradle/`` to apply it globally, or at the root of the Gradle project to +apply it at project level. +It can also be passed to command line with ``-Penable.ivy.descriptor.default=false`` option. + + + +Force Ivy Descriptor Publication When Disabled by Default +--------------------------------------------------------- + +Even when Ivy descriptor publication is globally disabled with the Gradle property, it can be forced in a project by adding ``withIvyDescriptor()`` to the ``microej`` block +in ``build.gradle.kts`` file:: + + microej { + withIvyDescriptor() + } + +.. + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/SDK6UserGuide/howtos/index.rst b/SDK6UserGuide/howtos/index.rst index 9c1032755..9b5f269ec 100644 --- a/SDK6UserGuide/howtos/index.rst +++ b/SDK6UserGuide/howtos/index.rst @@ -18,6 +18,7 @@ How-to Guides buildExecutableWithMultipleVeePorts createCustomConfigurationInIDE useFeatureEntryPointClass + disableIvyDescriptorPublication .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free diff --git a/SDK6UserGuide/howtos/installSnapshotPlugins.rst b/SDK6UserGuide/howtos/installSnapshotPlugins.rst index 258fd940e..0453a2b93 100644 --- a/SDK6UserGuide/howtos/installSnapshotPlugins.rst +++ b/SDK6UserGuide/howtos/installSnapshotPlugins.rst @@ -1,6 +1,6 @@ .. _sdk_6_install_plugin_snapshot: -How to Install MicroEJ Plugin Snapshot Version on Android Studio or IntelliJ IDEA +How To Install MicroEJ Plugin Snapshot Version on Android Studio or IntelliJ IDEA ================================================================================= If you want to test the version under development, the latest snapshot version of the plugin can be installed: diff --git a/SDK6UserGuide/images/dead_code.png b/SDK6UserGuide/images/dead_code.png new file mode 100644 index 000000000..42ddb78d7 Binary files /dev/null and b/SDK6UserGuide/images/dead_code.png differ diff --git a/SDK6UserGuide/images/gettingStarted/Board-NXP_i.MX-93-EK_100px.png b/SDK6UserGuide/images/gettingStarted/Board-NXP_i.MX-93-EK_100px.png new file mode 100644 index 000000000..f35796a80 Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/Board-NXP_i.MX-93-EK_100px.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-gradle-view.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-gradle-view.png new file mode 100755 index 000000000..1751474ca Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-gradle-view.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-import-demo.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-import-demo.png new file mode 100755 index 000000000..8f1eaa9fa Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-import-demo.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-intellij-variables.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-intellij-variables.png new file mode 100644 index 000000000..2adda09fc Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-intellij-variables.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-project-view.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-project-view.png new file mode 100755 index 000000000..fab60e2e8 Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-project-view.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-rufus.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-rufus.png new file mode 100644 index 000000000..6ef8d9ffb Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-rufus.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnDevice.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnDevice.png new file mode 100644 index 000000000..89b55465d Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnDevice.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnSimulator-modified.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnSimulator-modified.png new file mode 100755 index 000000000..61694317e Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnSimulator-modified.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnSimulator.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnSimulator.png new file mode 100755 index 000000000..a81d2bece Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-runOnSimulator.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-setup.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-setup.png new file mode 100644 index 000000000..c71076b55 Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-setup.png differ diff --git a/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-virtual-device.png b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-virtual-device.png new file mode 100755 index 000000000..068199d6f Binary files /dev/null and b/SDK6UserGuide/images/gettingStarted/iMX93/getting-started-virtual-device.png differ diff --git a/SDK6UserGuide/images/unreachable_code_setings.png b/SDK6UserGuide/images/unreachable_code_setings.png new file mode 100644 index 000000000..ec13d4a9b Binary files /dev/null and b/SDK6UserGuide/images/unreachable_code_setings.png differ diff --git a/SDK6UserGuide/images/vscode-add-attach-remote-configuration.png b/SDK6UserGuide/images/vscode-add-attach-remote-configuration.png new file mode 100644 index 000000000..a86618551 Binary files /dev/null and b/SDK6UserGuide/images/vscode-add-attach-remote-configuration.png differ diff --git a/SDK6UserGuide/images/vscode-add-breakpoint.png b/SDK6UserGuide/images/vscode-add-breakpoint.png new file mode 100644 index 000000000..3246bbae2 Binary files /dev/null and b/SDK6UserGuide/images/vscode-add-breakpoint.png differ diff --git a/SDK6UserGuide/images/vscode-attach-remote-program.png b/SDK6UserGuide/images/vscode-attach-remote-program.png new file mode 100644 index 000000000..935061704 Binary files /dev/null and b/SDK6UserGuide/images/vscode-attach-remote-program.png differ diff --git a/SDK6UserGuide/images/vscode-buildExecutable-gradle-project.png b/SDK6UserGuide/images/vscode-buildExecutable-gradle-project.png new file mode 100644 index 000000000..5a21c417b Binary files /dev/null and b/SDK6UserGuide/images/vscode-buildExecutable-gradle-project.png differ diff --git a/SDK6UserGuide/images/vscode-buildVirtualDevice-gradle-project.png b/SDK6UserGuide/images/vscode-buildVirtualDevice-gradle-project.png new file mode 100644 index 000000000..faf83e0a0 Binary files /dev/null and b/SDK6UserGuide/images/vscode-buildVirtualDevice-gradle-project.png differ diff --git a/SDK6UserGuide/images/vscode-configure-remote-debug.png b/SDK6UserGuide/images/vscode-configure-remote-debug.png new file mode 100644 index 000000000..61a7762f4 Binary files /dev/null and b/SDK6UserGuide/images/vscode-configure-remote-debug.png differ diff --git a/SDK6UserGuide/images/vscode-open-debug-launcher.png b/SDK6UserGuide/images/vscode-open-debug-launcher.png new file mode 100644 index 000000000..c1539c80c Binary files /dev/null and b/SDK6UserGuide/images/vscode-open-debug-launcher.png differ diff --git a/SDK6UserGuide/images/vscode-run-gradle-project.png b/SDK6UserGuide/images/vscode-run-gradle-project.png new file mode 100644 index 000000000..5a21c417b Binary files /dev/null and b/SDK6UserGuide/images/vscode-run-gradle-project.png differ diff --git a/SDK6UserGuide/images/vscode-runOnDevice-gradle-project.png b/SDK6UserGuide/images/vscode-runOnDevice-gradle-project.png new file mode 100644 index 000000000..2b379de93 Binary files /dev/null and b/SDK6UserGuide/images/vscode-runOnDevice-gradle-project.png differ diff --git a/SDK6UserGuide/images/vscode-select-java-debug.png b/SDK6UserGuide/images/vscode-select-java-debug.png new file mode 100644 index 000000000..004bc672f Binary files /dev/null and b/SDK6UserGuide/images/vscode-select-java-debug.png differ diff --git a/SDK6UserGuide/images/vscode-stopped-on-breakpoint.png b/SDK6UserGuide/images/vscode-stopped-on-breakpoint.png new file mode 100644 index 000000000..1b0254835 Binary files /dev/null and b/SDK6UserGuide/images/vscode-stopped-on-breakpoint.png differ diff --git a/SDK6UserGuide/images/vscode-test-gradle-project.png b/SDK6UserGuide/images/vscode-test-gradle-project.png new file mode 100644 index 000000000..0c2491b61 Binary files /dev/null and b/SDK6UserGuide/images/vscode-test-gradle-project.png differ diff --git a/SDK6UserGuide/images/vscode_java_extensions.png b/SDK6UserGuide/images/vscode_java_extensions.png new file mode 100644 index 000000000..9a5743273 Binary files /dev/null and b/SDK6UserGuide/images/vscode_java_extensions.png differ diff --git a/SDK6UserGuide/index.rst b/SDK6UserGuide/index.rst index 6e2dc2289..e99aec41f 100644 --- a/SDK6UserGuide/index.rst +++ b/SDK6UserGuide/index.rst @@ -46,6 +46,7 @@ The SDK is licensed under the :ref:`SDK End User License Agreement (EULA) `__ or `Oracle `__. +you can download and install one from `Adoptium `__ or `Oracle `__. .. _sdk_6_install_gradle: @@ -114,6 +114,7 @@ The three following IDEs are supported: - `Android Studio `__ - Minimum supported version is ``Hedgehog - 2023.1.1``. - `IntelliJ IDEA `__ (Community or Ultimate edition) - Minimum supported version is ``2021.2``. - `Eclipse IDE for Java Developers `__ - Minimum supported version is ``2022-03``. +- `Visual Studio Code `__ - Minimum supported version is ``1.89.0``. Follow their respective documentation to install one of them. @@ -122,10 +123,10 @@ These 3 IDEs come with the Gradle plugin installed by default. .. _sdk_6_install_ide_plugin: -Install the IDE Plugin ----------------------- +Install the IDE Plugins +----------------------- -Once your favorite IDE is installed, the MicroEJ plugin must be installed. +Once your favorite IDE is installed, plugins must be installed to develop MicroEJ Applications. .. tabs:: @@ -227,6 +228,29 @@ Once your favorite IDE is installed, the MicroEJ plugin must be installed. - In the upcoming window, click on the :guilabel:`Restart Now` button. + .. tab:: Visual Studio Code + + MicroEJ does not provide a dedicated plugin for VS Code, but Microsoft provides a plugin that brings a useful collection of plugins for Java + called `Extension Pack for Java `__. To install this plugin: + + - In Visual Studio Code, open the :guilabel:`Extensions` tab (Ctrl+Shift+X) + - In the search field, type ``extension pack for Java``: + + .. figure:: images/vscode_java_extensions.png + :alt: VS Code Java Plugins Installation + :align: center + :scale: 70% + + VS Code Java Plugins Installation + + - Click on the :guilabel:`Install` button of the extension + + .. warning:: + Unlike other supported IDEs (Android Studio/IntelliJ IDEA/Eclipse), there is no MicroEJ plugin which removes + the JDK dependency. As a result, `IntelliSense `__ may propose classes and methods from the JDK which are + not present in your project dependencies. + + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDK6UserGuide/licenses_sentinel.rst b/SDK6UserGuide/licenses_sentinel.rst new file mode 100644 index 000000000..2c458212e --- /dev/null +++ b/SDK6UserGuide/licenses_sentinel.rst @@ -0,0 +1,209 @@ +Sentinel License Management +=========================== + +In addition to single-workstation license based on a hardware dongle, MICROEJ SDK supports floating licenses based on Thales Sentinel LDK solution. + +This chapter contains instructions that will allow you to setup Sentinel environment and activate your license. + +There are two main steps: + +#. First, your System Administrator has to :ref:`setup the Sentinel Floating License Server ` on a host machine. +#. Then, on your Developer workstation, proceed with the :ref:`setup of the Sentinel client for the SDK `. + +.. figure:: images/sentinel_architecture.png + +.. note:: + + Floating License requires :ref:`Architecture 8.1.0 ` or higher (Production only). + +.. _setup_sentinel_floating_license_server: + +Setup the Sentinel Floating License Server +------------------------------------------ + +This section contains instructions for the System Administrator to setup the Sentinel Floating License Server. + +- Choose a machine to host the Sentinel Floating License Server. + The host machine must be choosen with care, as its fingerprint will be required to generate the license file. + Especially, you have to choose a host machine that is accessible through the network to all your developer workstations. +- Install the :ref:`Sentinel LDK Run-time Environment (RTE) ` on the host machine. +- On the host machine, open a web browser. +- Browse ``http://:1947`` to open the Sentinel Admin Control Center. +- Go to :guilabel:`Sentinel Keys` tab and click on :guilabel:`Fingerprint` button to download the ``*.c2v`` file. + + .. figure:: images/sentinel_rte_server_get_fingerprint.png + :scale: 90% + +- The ``*.c2v`` file stands for `Customer to Vendor`. Send this file to your MicroEJ sales representative. +- Wait until MicroEJ prepares your license key. Then you will receive a ``.v2c`` file. + The ``*.v2c`` file stands for `Vendor to Customer`. +- On the host machine, go back to the Sentinel Admin Control Center. +- Click on :guilabel:`Update/Attach` tab. +- Click on :guilabel:`Select File...` button and browse the ``.v2c`` file. +- Click on :guilabel:`Apply File` button. + +In :guilabel:`Sentinel Keys` tab, you should see the successfully installed license key: + +.. figure:: images/sentinel_rte_server_installed_license.png + :scale: 90% + +- Configure the host machine to open the IP port ``1947`` for TCP, UDP, TCP6, UDP6. +- Optionally, you can set a printable name for the Sentinel Floating License Server that will be displayed on the Developer workstation license list. + + - Go to :guilabel:`Configuration` > :guilabel:`Basic Settings` tab. + - Update the :guilabel:`Machine Name` text field (e.g. ``central-sentinel-server``). + - Click on :guilabel:`Submit` button. + +Your Sentinel Floating License Server is successfully configured. All you have to do is to share the host machine IP address to your MicroEJ Developers. + +.. _setup_sentinel_developer_workstation: + +Setup the Developer Workstation +------------------------------- + +This section contains instructions for the MicroEJ Developer to setup its workstation in order to connect a Sentinel Floating License Server. + +- Install the :ref:`Sentinel LDK Run-time Environment (RTE) ` on your workstation. +- Install the Sentinel Java Client. The Sentinel Java client is an OS specific shared library that must be made accessible to your Java Runtime Environment that will run the SDK. + + - **Windows** + + - Put ``MicroEJ_library\hasp_windows_x64_37102.dll`` file in the system folder (``%SystemRoot%\system32``) if you have administrator rights on your machine. + + Otherwise drop the ``hasp_windows_x64_37102.dll`` file beside ``java.exe`` executable of the Java Development Kit (JDK) used to run the SDK. + + - **Linux** + + - Get ``MicroEJ_library/libhasp_linux_x86_64_37102.so`` file and copy it in a directory of your choice + - Set ``LD_LIBRARY_PATH`` variable with command ``export LD_LIBRARY_PATH=:$LD_LIBRARY_PATH``. + + This modification has to be setup at session startup (e.g: using ``.bashrc`` file) to ensure that OS is properly configured before running the SDK. + + - **macOS** + + - Get ``MicroEJ_library/hasp_darwin_37102.dylib`` file and copy it in a directory of your choice + - Set ``DYLD_LIBRARY_PATH`` variable with command ``export DYLD_LIBRARY_PATH=:$DYLD_LIBRARY_PATH``. + + This modification has to be setup at session startup (e.g: using ``.bashrc`` file) to ensure that OS is properly configured before running the SDK. + +- Configure the Remote Floating License Server. + + - On the developer workstation, open a web browser. + - Browse http://localhost:1947 to open the Sentinel Admin Control Center. + - Go to :guilabel:`Configuration` > :guilabel:`Access to Remote License Managers`. + - Check :guilabel:`Allow Access to Remote Licenses`. + - Uncheck :guilabel:`Broadcast Search for Remote Licenses`. + - In :guilabel:`Remote License Search Parameters`, add the Floating License Server IP address that should have been shared by your System Administrator. + + .. image:: images/sentinel_rte_client_remote_config.png + + - Click on :guilabel:`Submit` button. + - Your computer should now have access to the licenses configured on the Floating License Server. + In :guilabel:`Sentinel Keys` tab, you should see the license key provided by your Floating License Server (e.g. ``central-sentinel-server``). + + .. image:: images/sentinel_rte_client_installed_license.png + +.. _setup_sentinel_runtime: + +Runtime Installation Instructions and Troubleshooting +----------------------------------------------------- + +.. _sentinel_rte_installation: + +Install the Sentinel LDK Run-time Environment (RTE) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`Sentinel LDK Run-time Environment `__ enables your protected software to run by communicating with Sentinel protection keys. +It must be installed by each developer to :ref:`setup its workstation ` and also by your System Administrator to :ref:`setup the Sentinel Floating License Server `. + +First, download `Sentinel_RTE_Installation-1.1.0.zip `__ file. It contains installer for Windows, macOS and Linux. + +Installation for Windows +"""""""""""""""""""""""" + +- Get ``haspdinst_37102.exe`` file +- Type ``haspdinst_37102.exe -i`` in the command line. The installation or upgrade process is performed automatically. A message is displayed informing you that the Sentinel LDK Run-time Environment was successfully installed + +.. note:: + To uninstall Sentinel RTE, type ``haspdinst_37102.exe -r`` in the command line. A message is displayed informing you that the Sentinel LDK Run-time Environment was successfully removed. + +Installation for Linux +"""""""""""""""""""""" + +Get ``aksusbd_37102-10.12.1.tar.gz`` file and extract it. The installation packages are in the directory ``pkg``, as root enter the following command: + +- For RedHat, SUSE, or CentOS 64-bit Intel systems: ``rpm -i aksusbd-9.14-1.x86_64.rpm`` +- For Ubuntu or Debian 64-bit Intel systems: ``dpkg -i aksusbd_9.14-1_amd64.deb`` +- Copy ``aksusbd-9.14.1/haspvlib_37102.so`` and ``aksusbd-9.14.1/haspvlib_x86_64_37102.so`` to ``/var/hasplm`` directory + +.. note:: + All install/uninstall commands must be executed with root rights. On Ubuntu, prefix the commands with the ``sudo`` command. On other Linux distributions, use the ``su`` utility to become root in the terminal window. + +Installation for macOS +"""""""""""""""""""""" + +- Get ``Sentinel_Runtime_37102.tar`` file +- In ``SentinelRuntimeInstaller.framework/Versions/A/Resources/`` double-click on ``Sentinel_Runtime.pkg`` +- Double-click the Install Sentinel Runtime Environment disk image icon. The installer wizard is launched +- Follow the instructions of the installer wizard until the installation is complete. The first time that you run Admin Control Center and submit configuration changes, ``hasplmd`` creates configuration files in ``/private/etc/hasplm/`` + + +Check Activation with the Command Line Tool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify access to the Sentinel license on the workstation where the SDK executes, run the debug tool as following: + +#. Open a terminal +#. Change directory to a Production VEE Port +#. Execute the command: + + .. code:: console + + java -Djava.library.path=resources/os/[OS_NAME] -jar licenseManager/licenseManagerProduct.jar + + with ``OS_NAME`` set to ``Windows64`` for Windows OS, ``Linux64`` for Linux OS, ``Mac`` for macOS x86_64 (Intel chip) or ``MacA64`` for macOS aarch64 (M1 chip). + +If your Sentinel license has been properly activated, you should get the following output: + +.. code:: console + + [DEBUG] ===== MicroEJ Sentinel Debug Tool ===== + [DEBUG] => Detected Sentinel License Key ID: XXXXXXXXXXXXXXXX. + [DEBUG] => Detected MicroEJ License valid until YYYY-MM-DD. + [DEBUG] ===== SUCCESS ===== + +Troubleshooting +~~~~~~~~~~~~~~~ + +Sentinel API dynamic library not found (code 400) +""""""""""""""""""""""""""""""""""""""""""""""""" + +The following error occurred when the library ``hasp_[os]_37102.[ext]`` has not been found. Please refer to :ref:`setup_sentinel_developer_workstation`. +Specifically, if you are on Linux, check the library is readable with the command ``file libhasp_linux_x86_64_37102.so``. + +Sentinel key not found (code 7) +""""""""""""""""""""""""""""""" + +The following error occurred when there is no Sentinel license available. Go to http://localhost:1947/int/devices.html and check your Sentinel licenses. You should see at least one installed license key: + +.. figure:: images/sentinel_rte_client_installed_license.png + :alt: Sentinel Installed License(s) View + :align: center + :scale: 75% + +Make sure you correctly configured the access to the Sentinel Floating License Server. Please refer to :ref:`setup_sentinel_developer_workstation`. + +No Administrator Privileges on Developer Workstation +"""""""""""""""""""""""""""""""""""""""""""""""""""" + +:ref:`Sentinel LDK RTE installation ` requires administrator privileges and facilitates the setup of the network server. +However, it is not necessary to be installed on the developer workstation in case of floating licenses. +See this `documentation `__ for more details. +If you are in such situation, please can contact `our support team `_. + +.. + | Copyright 2008-2025, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. \ No newline at end of file diff --git a/SDK6UserGuide/limitations.rst b/SDK6UserGuide/limitations.rst index 8f4de3919..272844c19 100644 --- a/SDK6UserGuide/limitations.rst +++ b/SDK6UserGuide/limitations.rst @@ -16,12 +16,16 @@ The SDK 6 allows to: - Build the Virtual Device of an Application. - Use the Stack Trace Reader. - Use the Code Coverage Analyzer. +- Use the Local Deploy. +- Use the Serial to Socket Transmitter. - Use the Font Designer, Memory Map Analyzer, Heap Analyzer and Front Panel Designer tools. +- Build a Kernel Application. +- Build a Runtiime API. Therefore, it does not support all the features of the SDK 5, especially: -- Build of Foundation Libraries, VEE Ports or any other component type except Applications, Add-On Libraries and Mocks. -- Launch of some MicroEJ tools, such as the Local Deploy, the Serial to Socket Transmitter or the Kernel Metadata Generator. +- Build of Foundation Libraries, VEE Ports, Packs and Offline Repositories. +- Launch of some MicroEJ tools, such as the Kernel Metadata Generator. If you need these features, you have to use :ref:`the SDK 5 `. diff --git a/SDK6UserGuide/migrateMMMProject.rst b/SDK6UserGuide/migrateMMMProject.rst index d24827630..4e89704e9 100644 --- a/SDK6UserGuide/migrateMMMProject.rst +++ b/SDK6UserGuide/migrateMMMProject.rst @@ -60,7 +60,7 @@ The MMM build type defined in the ``module.ivy`` file with the ``ea:build`` tag For example, here is the block to add at the beginning of the file to migrate a ``build-microej-javalib`` MMM module:: plugins { - id("com.microej.gradle.addon-library") version "0.16.0" + id("com.microej.gradle.addon-library") version "0.18.0" } The mapping between MMM build types and Gradle plugins is: @@ -252,7 +252,7 @@ This section gives an example of migration from a ``module.ivy`` file to a ``bui :caption: build.gradle.kts plugins { - id("com.microej.gradle.application") version "0.16.0" + id("com.microej.gradle.application") version "0.18.0" } group = "com.mycompany" diff --git a/SDK6UserGuide/moduleNatures.rst b/SDK6UserGuide/moduleNatures.rst index 0c7c1e817..061f994bf 100644 --- a/SDK6UserGuide/moduleNatures.rst +++ b/SDK6UserGuide/moduleNatures.rst @@ -26,10 +26,9 @@ This plugin adds the following tasks to your project: - tasks of the `Gradle Java plugin `__ - :ref:`sdk6_module_natures.tasks.adp` - :ref:`sdk6_module_natures.tasks.loadVee` -- :ref:`sdk6_module_natures.tasks.loadApplicationConfiguration` - :ref:`sdk6_module_natures.tasks.runOnSimulator` -- :ref:`sdk6_module_natures.tasks.loadTestApplicationConfiguration` - :ref:`sdk6_module_natures.tasks.checkModule` +- :ref:`sdk6_module_natures.tasks.execTool` .. graphviz:: graphAddonLibraryModule.dot @@ -54,19 +53,17 @@ This plugin adds the following tasks to your project: - tasks of the `Gradle Java plugin `__ - :ref:`sdk6_module_natures.tasks.adp` - :ref:`sdk6_module_natures.tasks.loadVee` -- :ref:`sdk6_module_natures.tasks.loadApplicationConfiguration` - :ref:`sdk6_module_natures.tasks.runOnSimulator` -- :ref:`sdk6_module_natures.tasks.loadTestApplicationConfiguration` - :ref:`sdk6_module_natures.tasks.checkModule` -- :ref:`sdk6_module_natures.tasks.loadExecutableConfiguration` +- :ref:`sdk6_module_natures.tasks.buildApplicationObjectFile` - :ref:`sdk6_module_natures.tasks.buildExecutable` - :ref:`sdk6_module_natures.tasks.buildWPK` - :ref:`sdk6_module_natures.tasks.buildVirtualDevice` - :ref:`sdk6_module_natures.tasks.loadKernelExecutable` -- :ref:`sdk6_module_natures.tasks.loadFeatureConfiguration` - :ref:`sdk6_module_natures.tasks.buildFeature` - :ref:`sdk6_module_natures.tasks.runOnDevice` - :ref:`sdk6_module_natures.tasks.execTool` +- :ref:`sdk6_module_natures.tasks.generateApplicationWrapper` - :ref:`sdk6_module_natures.tasks.compileWrapperJava` .. graphviz:: graphApplicationModule.dot @@ -114,6 +111,29 @@ This plugin adds the following tasks to your project: This module nature inherits from the configuration of all its tasks. +.. _sdk6_module_natures.runtime-api: + +Runtime API +----------- + +**Plugin Name**: ``com.microej.gradle.runtime-api`` + +**Tasks**: + +This plugin adds the following tasks to your project: + +- tasks of the `Gradle Java plugin `__ +- :ref:`sdk6_module_natures.tasks.checkModule` +- :ref:`sdk6_module_natures.tasks.shrinkRuntimeApi` +- :ref:`sdk6_module_natures.tasks.compileRuntimeApi` +- :ref:`sdk6_module_natures.tasks.builRuntimeApiJar` + +.. graphviz:: graphRuntimeApiModule.dot + +**Configuration**: + +This module nature inherits from the configuration of all its tasks. + .. _sdk6_module_natures.tasks: Tasks @@ -169,16 +189,18 @@ This task is used by the following module natures: - :ref:`sdk6_module_natures.addon_lib` - :ref:`sdk6_module_natures.application` -.. _sdk6_module_natures.tasks.loadApplicationConfiguration: +The ``loadVee`` task is used internally by the SDK and it is not intended to be executed by the user. -loadApplicationConfiguration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _sdk6_module_natures.tasks.runOnSimulator: + +runOnSimulator +^^^^^^^^^^^^^^ -**Description**: Loads the configuration for the Application to execute. +**Description**: Executes the Application with the Simulator. **Inputs**: -- The extracted VEE Port folder +- The extracted VEE folder - The project classpath which contains the MicroEJ dependent application classes and resources - The Full Qualified Name of the Application main class or Feature class - The folder containing the application configuration (``configuration``) @@ -186,10 +208,6 @@ loadApplicationConfiguration - The debug mode - The debug port -**Outputs**: - -- The configuration file with all the properties set to launch the application (``build/properties/target.properties``) - **Module Natures**: This task is used by the following module natures: @@ -220,47 +238,6 @@ For example: applicationEntryPoint = "com.company.Main" } -.. _sdk6_module_natures.tasks.runOnSimulator: - -runOnSimulator -^^^^^^^^^^^^^^ - -**Description**: Executes the Application with the Simulator. - -**Inputs**: - -- The extracted VEE Port folder -- The configuration file with all the properties set to launch the application (``build/properties/target.properties``) - -**Module Natures**: - -This task is used by the following module natures: - -- :ref:`sdk6_module_natures.addon_lib` -- :ref:`sdk6_module_natures.application` - -.. _sdk6_module_natures.tasks.loadTestApplicationConfiguration: - -loadTestApplicationConfiguration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Description**: Loads the configuration for the Test Application to execute. - -**Inputs**: - -- The extracted VEE Port folder - -**Outputs**: - -- The configuration file with all the properties set to launch the test application (``build/testsuite/properties/microej-testsuite.properties``) - -**Module Natures**: - -This task is used by the following module natures: - -- :ref:`sdk6_module_natures.addon_lib` -- :ref:`sdk6_module_natures.application` - .. _sdk6_module_natures.tasks.checkModule: checkModule @@ -279,6 +256,7 @@ This task is used by the following module natures: - :ref:`sdk6_module_natures.addon_lib` - :ref:`sdk6_module_natures.application` +- :ref:`sdk6_module_natures.runtime-api` **Configuration**: @@ -311,23 +289,24 @@ For example: checkers = "readme,license" } -.. _sdk6_module_natures.tasks.loadExecutableConfiguration: +.. _sdk6_module_natures.tasks.buildApplicationObjectFile: -loadExecutableConfiguration -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +buildApplicationObjectFile +^^^^^^^^^^^^^^^^^^^^^^^^^^ -**Description**: Loads the configuration to build the Executable of an Application. +**Description**: Build the object file of the Application. **Inputs**: - The extracted VEE Port folder - The project classpath which contains the MicroEJ dependent application classes and resources -- The Full Qualified Name of the Application main class +- The Full Qualified Name of the Application EntryPoint - The folder containing the application configuration (``configuration``) **Outputs**: -- The configuration file with all the properties set to launch the build of the Executable (``build/properties/target.properties``) +- The object file (.o) of the Application and the archive of the build files (``build/application/object/bsp/lib/microejapp.o``) +- The Zip file containing the generated build files (``build/application/applicationObjectBuildFiles.zip``) **Module Natures**: @@ -335,6 +314,8 @@ This task is used by the following module natures: - :ref:`sdk6_module_natures.application` +The ``buildApplicationObjectFile`` task is used internally by the SDK and it is not intended to be executed by the user. + .. _sdk6_module_natures.tasks.buildExecutable: buildExecutable @@ -345,13 +326,12 @@ buildExecutable **Inputs**: - The extracted VEE Port folder -- The configuration file with all the properties set to launch the build of the Executable (``build/properties/target.properties``) -- The project build classpath +- The folder containing the application configuration (``configuration``) +- The object file (.o) of the Application **Outputs**: -- The directory in which the Executable file and the build files are generated (``build/executable/application``) -- The Zip file containing the generated build files (``build/executable/buildFiles.zip``) +- The directory in which the Executable file and the build files are generated (``build/application/executable``) **Module Natures**: @@ -391,6 +371,8 @@ This task is used by the following module natures: buildVirtualDevice ^^^^^^^^^^^^^^^^^^ +**Description**: Builds the Virtual Device of an Application. + **Inputs**: - The extracted VEE Port folder @@ -402,8 +384,6 @@ buildVirtualDevice - The Zip file of the Virtual Device (``build/libs/-virtualDevice.zip``) -**Description**: Build the Virtual Device of an Application. - **Module Natures**: This task is used by the following module natures: @@ -431,47 +411,26 @@ This task is used by the following module natures: - :ref:`sdk6_module_natures.application` -.. _sdk6_module_natures.tasks.loadFeatureConfiguration: - -loadFeatureConfiguration -^^^^^^^^^^^^^^^^^^^^^^^^ - -**Description**: Loads the configuration to build the Feature file of an Application. - -**Inputs**: - -- The Kernel Virtual Device -- The folder containing the Kernel Executable file (``build/kernelExecutable``) -- The project classpath -- The path of the folder where the Feature file must be generated (``build/feature``) - -**Outputs**: - -- The configuration file with all the properties set to launch the build of the Feature file (``build/properties/target.properties``) - -**Module Natures**: - -This task is used by the following module natures: - -- :ref:`sdk6_module_natures.application` +The ``loadKernelExecutable`` task is used internally by the SDK and it is not intended to be executed by the user. .. _sdk6_module_natures.tasks.buildFeature: buildFeature ^^^^^^^^^^^^ -**Description**: Build the Feature file of an Application. +**Description**: Builds the Feature file of an Application. **Inputs**: - The Kernel Virtual Device - The folder containing the Kernel Executable file (``build/kernelExecutable``) - The project classpath +- The path of the folder where the Feature file must be generated (``build/feature/application``) **Outputs**: -- The folder in which the Feature file is generated (``build/feature``) - +- The generated Feature file (``build/feature/application/application.fo``) +- The Zip file containing the generated build files (``build/"libs/-feature.zip"``) **Module Natures**: @@ -482,7 +441,7 @@ This task is used by the following module natures: .. _sdk6_module_natures.tasks.runOnDevice: runOnDevice -^^^^^^^^^^^^ +^^^^^^^^^^^ **Description**: Runs the Executable on a Device. @@ -511,7 +470,7 @@ buildMockRip **Outputs**: -- the RIP file of the Mock (``build/libs/-.rip``) +- the RIP file of the Mock (``build/libs/-.rip``) **Module Natures**: @@ -536,18 +495,45 @@ execTool This task is used by the following module natures: +- :ref:`sdk6_module_natures.addon_lib` - :ref:`sdk6_module_natures.application` +.. _sdk6_module_natures.tasks.generateApplicationWrapper: + +generateApplicationWrapper +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Description**: Generates the :ref:`gradle_application_wrapper_chapter` to be able to run the Application on a VEE Port and a Kernel. + +**Inputs**: + +- The Application EntryPoint +- The configuration directory of the project +- The project classpath which contains the MicroEJ dependent application classes and resources + +**Outputs**: + +- The directory in which the Wrapper Java class has been generated (``build/generated/microej-app-wrapper/java``) +- The directory in which the Wrapper resources have been generated (``build/generated/microej-app-wrapper/resources``) + +**Module Natures**: + +This task is used by the following module natures: + +- :ref:`sdk6_module_natures.application` + +The ``generateApplicationWrapper`` task is used internally by the SDK and it is not intended to be executed by the user. + .. _sdk6_module_natures.tasks.compileWrapperJava: compileWrapperJava ^^^^^^^^^^^^^^^^^^ -**Description**: Compiles Application wrapper class to be able to run the Application on a VEE Port and a Kernel. +**Description**: Compiles the :ref:`gradle_application_wrapper_chapter` to be able to run the Application on a VEE Port and a Kernel. **Inputs**: -- The project classpath which contains the MicroEJ dependent application classes and resources +- The directory containing the Wrapper Java class (``build/generated/microej-app-wrapper/java``) **Outputs**: @@ -559,6 +545,80 @@ This task is used by the following module natures: - :ref:`sdk6_module_natures.application` +The ``compileWrapperJava`` task is used internally by the SDK and it is not intended to be executed by the user. + +.. _sdk6_module_natures.tasks.shrinkRuntimeApi: + +shrinkRuntimeApi +^^^^^^^^^^^^^^^^ + +**Description**: Shrinks the Java source files according to the provided :ref:`Kernel APIs `. + +**Inputs**: + +- Project Kernel API (``src/main/resources/kernel.api``) +- Project Java sources (``src/main/java``) +- The Kernel API files of the Runtime classpath. + +**Outputs**: + +- The directory in which shrunk Java sources are generated (``build/runtimeApi/shrunkSources``) + +**Module Natures**: + +This task is used by the following module natures: + +- :ref:`sdk6_module_natures.runtime-api` + +The ``shrinkRuntimeApi`` task is used internally by the SDK and it is not intended to be executed by the user. + +.. _sdk6_module_natures.tasks.compileRuntimeApi: + +compileRuntimeApi +^^^^^^^^^^^^^^^^^ + +**Description**: Compiles the Runtime API :ref:`Kernel APIs `. + +**Inputs**: + +- The directory in which shrunk Java sources are generated (``build/runtimeApi/shrunkSources``) +- The project classpath + +**Outputs**: + +- The directory in which shrunk Java classes are generated (``build/runtimeApi/shrunkClasses``) + +**Module Natures**: + +This task is used by the following module natures: + +- :ref:`sdk6_module_natures.runtime-api` + +The ``compileRuntimeApi`` task is used internally by the SDK and it is not intended to be executed by the user. + +.. _sdk6_module_natures.tasks.builRuntimeApiJar: + +buildRuntimeApiJar +^^^^^^^^^^^^^^^^^^ + +**Description**: Builds the Runtime API Jar file. + +**Inputs**: + +- The directory in which shrunk Java classes are generated (``build/runtimeApi/shrunkClasses``) + +**Outputs**: + +- The Jar file of the Runtime API (``build/libs/--runtime-api.jar``) + +**Module Natures**: + +This task is used by the following module natures: + +- :ref:`sdk6_module_natures.runtime-api` + +The ``buildRuntimeApiJar`` task is used internally by the SDK and it is not intended to be executed by the user. + .. _gradle_global_build_options: Global Properties diff --git a/SDK6UserGuide/publishProject.rst b/SDK6UserGuide/publishProject.rst index 25f9c9130..facd1093d 100644 --- a/SDK6UserGuide/publishProject.rst +++ b/SDK6UserGuide/publishProject.rst @@ -18,6 +18,10 @@ The requirements to publish a module are: group = "com.mycompany" version = "1.0.0" + .. warning:: + + Refer to :ref:`Manage Versioning page ` to know how to version your module. + - Declaring a ``maven`` publication repository. This can be done in the build file for example, with:: @@ -48,6 +52,11 @@ The following artifacts are automatically published: - The WPK file, if the project is an Application. - The Virtual Device, if the project is an Application. +.. note:: + + Ivy descriptor publication can be disabled. You can refer to :ref:`disable Ivy Descriptor publication How-to page ` + if you don't need to publish Ivy descriptor. + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDK6UserGuide/runOnDevice.rst b/SDK6UserGuide/runOnDevice.rst index 84dee90b5..0d13f0296 100644 --- a/SDK6UserGuide/runOnDevice.rst +++ b/SDK6UserGuide/runOnDevice.rst @@ -27,6 +27,13 @@ Once these prerequisites are fulfilled, the Application can be deployed on the D :width: 30% :align: center + | + + .. warning:: + Android Studio does not allow to run multiple Gradle tasks in parallel. + If you still want to execute several Gradle tasks simultaneously, + you can launch them from a terminal with the Gradle Command Line Interface (CLI). + .. tab:: Eclipse By double-clicking on the ``runOnDevice`` task in the Gradle tasks view: @@ -35,6 +42,14 @@ Once these prerequisites are fulfilled, the Application can be deployed on the D :width: 50% :align: center + .. tab:: Visual Studio Code + + By double-clicking on the ``runOnDevice`` task in the Gradle tasks view: + + .. image:: images/vscode-runOnDevice-gradle-project.png + :width: 25% + :align: center + .. tab:: Command Line Interface From the command line interface:: @@ -50,6 +65,22 @@ where ``RUN_SCRIPT_PATH`` is the absolute path to the ``run.[sh|bat]`` script of The Application Executable is now deployed on the Device. +Deploying the Executable without building it +-------------------------------------------- + +When executing the ``runOnDevice`` task, the Executable is always rebuilt, +even if nothing has changed in the project. +This ensures that the Executable is always up-to-date, no matter if the BSP has changed or not. + +If you want to deploy the Executable on the device without building it (so simply +deploying the Executable file already available in the project ``build`` folder), +you can exclude the ``buildExecutable`` task:: + + $ ./gradlew runOnDevice -x buildExecutable + +You can execute such a command in IDEs by creating custom configurations, +as explained in :ref:`sdk_6_howto_create_custom_configuration_in_ide`. + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDK6UserGuide/runOnSimulator.rst b/SDK6UserGuide/runOnSimulator.rst index 5d465a5ad..8fda23b2f 100644 --- a/SDK6UserGuide/runOnSimulator.rst +++ b/SDK6UserGuide/runOnSimulator.rst @@ -25,6 +25,13 @@ Once these prerequisites are fulfilled, the Application can be started with the :width: 30% :align: center + | + + .. warning:: + Android Studio does not allow to run multiple Gradle tasks in parallel. + If you still want to execute several Gradle tasks simultaneously, + you can launch them from a terminal with the Gradle Command Line Interface (CLI). + .. tab:: Eclipse By double-clicking on the ``runOnSimulator`` task in the Gradle tasks view: @@ -33,6 +40,14 @@ Once these prerequisites are fulfilled, the Application can be started with the :width: 50% :align: center + .. tab:: Visual Studio Code + + By double-clicking on the ``runOnSimulator`` task in the Gradle tasks view: + + .. image:: images/vscode-run-gradle-project.png + :width: 25% + :align: center + .. tab:: Command Line Interface From the command line interface:: @@ -93,23 +108,79 @@ If you want to connect the IDE debugger: Android Studio and IntelliJ IDEA need an Architecture 8.1 or higher for debug mode. - Add a breakpoint in your Application code. - - Click on ``Run > Edit Configurations...``. - - Click on ``+`` button (``Add New Configuration``). - - Select ``Remote JVM Debug``. - - Click on the ``New launch configuration`` button. - - Give a name to the launcher in the ``Name`` field. + - Click on :guilabel:`Run` > :guilabel:`Edit Configurations...`. + - Click on :guilabel:`+` button (:guilabel:`Add New Configuration`). + - Select :guilabel:`Remote JVM Debug`. + - Click on the :guilabel:`New launch configuration` button. + - Give a name to the launcher in the :guilabel:`Name` field. - Set the debug host and port. - - Click on the ``Debug`` button. + - Click on the :guilabel:`Debug` button. .. tab:: Eclipse - Add a breakpoint in your Application code. - - Click on ``Run > Debug Configurations...``. - - Select ``Remote Java Application``. - - Click on the ``New launch configuration`` button. - - Give a name to the launcher in the ``Name`` field. + - Click on :guilabel:`Run` > :guilabel:`Debug Configurations...`. + - Select :guilabel:`Remote Java Application`. + - Click on the :guilabel:`New launch configuration` button. + - Give a name to the launcher in the :guilabel:`Name` field. - Set the debug host and port. - - Click on the ``Debug`` button. + - Click on the :guilabel:`Debug` button. + + .. tab:: Visual Studio Code + + .. warning:: + VS Code needs an Architecture 8.1 or higher for debug mode. + + - Add a breakpoint in your Application code. + + .. figure:: images/vscode-add-breakpoint.png + :alt: VS Code add a breakpoint + :align: center + :scale: 70% + + - Click on the :guilabel:`Run and Debug (Ctrl+Shift+D)` icon on the right panel. + - Click on ``create a launch.json file`` in the opened panel. + + .. figure:: images/vscode-open-debug-launcher.png + :alt: VS Code open debug launchers + :align: center + :scale: 70% + + - Click on the ``Java`` entry proposed in the search field. + + .. figure:: images/vscode-select-java-debug.png + :alt: VS Code select Java debug + :align: center + :scale: 70% + + - Click on :guilabel:`Add Configuration` button + - Select ``{} Java: Attach to Remote Program`` entry in the popup list. + + .. figure:: images/vscode-add-attach-remote-configuration.png + :alt: VS Code add attach remote debug configuration + :align: center + :scale: 70% + + - Set ``localhost`` as ``hostName`` and the ``port`` (default is ``1200``) in the generated json. + + .. figure:: images/vscode-configure-remote-debug.png + :alt: VS Code configure remote debug in json + :align: center + :scale: 70% + + - Select ``Attach to Remote Program`` in the selection box of the launcher. + + .. figure:: images/vscode-attach-remote-program.png + :alt: VS Code run debug + :align: center + :scale: 70% + + - Click on the ``Start`` button + + .. figure:: images/vscode-stopped-on-breakpoint.png + :alt: VS Code stopped on breakpoint + :align: center + :scale: 70% The debugger should connect to the Simulator and you should be able to debug your Application. diff --git a/SDK6UserGuide/sdk6ChangeLog.rst b/SDK6UserGuide/sdk6ChangeLog.rst index 29d98e721..17d271f57 100644 --- a/SDK6UserGuide/sdk6ChangeLog.rst +++ b/SDK6UserGuide/sdk6ChangeLog.rst @@ -3,6 +3,73 @@ Changelog --------- +.. _changelog-0.18.0: + +[0.18.0] - 2024-08-22 +~~~~~~~~~~~~~~~~~~~~~ + +Added +""""" + +- Allow to build a VEE Port. +- Retry tests when they fail to avoid flaky tests (mainly due to license check) to fail the whole build. +- Support build incremental when using a published VEE Port with Full BSP Connection. +- Add the plugin `com.microej.gradle.runtime-api` to build a Runtime API. +- Allow to enable/disable the publication of the Ivy descriptor. +- Allow to run dependent applications on simulator (declared with `microejApplication`). + +Fixed +""""" + +- Fix publication to add dependencies defined with MicroEJ configurations to the ``.module`` and ``.pom`` files. +- Comment the ``stop`` method of the generated Wrapper class to prevent potential Sonar issue. +- Fix MicroEJ Test Engine compatibility with Gradle 8.6 and higher. +- Allow to run a Virtual Device via its launchers on a JDK version higher than 11. +- Fix build failure on multi-project with several applications depending on a kernel as project dependency. +- Some projects are not configured to be built with Java 1.7 when imported in Eclipse. +- Fix feature not found when launching a Virtual Device with installed applications. + +.. _changelog-0.17.0: + +[0.17.0] - 2024-05-30 +~~~~~~~~~~~~~~~~~~~~~ + +Added +""""" + +- Allow to add tools to a Virtual Device. +- Allow to fetch Runtime APIs with the ``microejRuntimeApi`` configuration. + +Changed +""""""" + +- Merge the ``loadXXXConfiguration`` tasks with their matching task. +- Split ``buildExecutable`` in 2 tasks to support incremental build of the ``microejapp.o`` file. +- Make FeatureEntryPoint take priority over main method when generating the Application entryPoint wrapper. + +Fixed +""""" + +- Re-Generate the Application entrypoint wrapper if the entrypoint class is + modified, if the ``applicationEntryPoint`` property is changed or if the resources changed. +- Simplify Ant classpath when executing an Ant script to avoid too long classpath and support multiple Windows drives. +- Append Applications provided with the ``microejApplication`` configuration to a Virtual Device. +- Make sure to always generate the Kernel certificate if it does not exist. +- Remove deprecated APIs used to generate Application certificates. +- Log filter in Ant scripts. +- Print last relevant logs as exception message when Ant script execution fails. +- Fix failing Javadoc generation when using EDC 1.3.6 and Null Analysis annotations. +- Make the generated Wrapper Feature class call the main method of the Application with an empty array as + parameter instead of null. +- Generate Application entrypoint wrapper if the entrypoint class extends a class implementing the + FeatureEntryPoint interface. +- Do not embed generated KF files in Application JAR to avoid switching in KF mode when executing an Application on a + VEE Port. +- Fix configurations used to fetch Kernels to avoid NPE during build when a project is provided + as dependency. +- Set ADP generated folders in the sourcesets to be detected by the IDEs. +- Make sure to copy the Assembly file in the BSP when it is generated. + .. _changelog-0.16.0: [0.16.0] - 2024-03-18 @@ -45,7 +112,7 @@ Fixed Added """"" -- Unify ``microejVeePort`` and ``microejKernel`` configurations into `microejVee`. +- Unify ``microejVeePort`` and ``microejKernel`` configurations into ``microejVee``. - Add verification of dependencies checksums during build. - Add the plugin ``com.microej.gradle.mock`` to build a Mock. - Mention the system property to accept SDK EULA in error message. diff --git a/SDK6UserGuide/serialToSocketTransmitter.rst b/SDK6UserGuide/serialToSocketTransmitter.rst new file mode 100644 index 000000000..44fd24a49 --- /dev/null +++ b/SDK6UserGuide/serialToSocketTransmitter.rst @@ -0,0 +1,88 @@ +.. _sdk6_tool_serial_to_socket: + +============================ +Serial to Socket Transmitter +============================ + + +Principle +========= + +The MicroEJ Serial to Socket Transmitter is a tool which +transfers all bytes from a serial port to a TCP client or TCP server. + +It is typically used to transfer the output traces of a testsuite executed on a device. + +Use +=== + +To start transfering data from the ``COM8`` serial port to the port ``5555``, +execute the ``execTool`` task as followed: + +.. code:: console + + ./gradlew execTool --name=serialToSocketTransmitter \ + --toolProperty="serail.to.socket.comm.port=COM8" \ + --toolProperty="serail.to.socket.comm.baudrate=115200" \ + --toolProperty="serail.to.socket.server.port=5555" \ + --console plain + + +Options +======= + +Serial Port +^^^^^^^^^^^ + +*Option Name*: ``serail.to.socket.comm.port`` + +*Default value*: ``COM0`` + +*Description*: Defines the COM port: + + +Windows - ``COM1``, ``COM2``, ``...``, ``COM*n*`` + + +Linux - ``/dev/ttyS0``, ``/dev/ttyUSB0``, ``...``, ``/dev/ttyS*n*``, +``/dev/ttyUSB*n*`` + + + +Baudrate +^^^^^^^^ + +*Option Name*: ``serail.to.socket.comm.baudrate`` + +*Default value*: ``115200`` + +*Available values*: + + +``9600`` + +``38400`` + +``57600`` + +``115200`` + + +*Description*: Defines the COM baudrate. + + +Socket Port +^^^^^^^^^^^ + +*Option Name*: ``serail.to.socket.server.port`` + +*Default value*: ``5555`` + +*Description*: Defines the TCP server port. + +.. + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/SDK6UserGuide/testProject.rst b/SDK6UserGuide/testProject.rst index 4dc8bdcf9..74c2cac04 100644 --- a/SDK6UserGuide/testProject.rst +++ b/SDK6UserGuide/testProject.rst @@ -126,6 +126,11 @@ This can be done manually or with IDE menu: - right-click on the ``src/test/java`` folder. - select :guilabel:`New` > :guilabel:`Other…` > :guilabel:`Java` > :guilabel:`JUnit` > :guilabel:`New JUnit Test Case`. + .. tab:: Visual Studio Code + + - right-click on the ``src/test/java`` folder in :guilabel:`JAVA PROJECTS` view. + - select the :guilabel:`+` icon (:guilabel:`New…`) > :guilabel:`Class`, then enter the test class name you want to create. + .. note:: Gradle allows to define alternative folders for test sources but it would require additional configuration, @@ -164,6 +169,14 @@ which means that the tests are also executed when launching one of these tasks. :width: 50% :align: center + .. tab:: Visual Studio Code + + In order to execute the testsuite from VS Code, double-click on the task in the Gradle tasks view: + + .. image:: images/vscode-test-gradle-project.png + :width: 25% + :align: center + .. tab:: Command Line Interface In order to execute the testsuite from the Command Line Interface, execute this command:: @@ -190,6 +203,7 @@ To generate the Code Coverage files (``.cc``) for each test, configure the test testTask.configure { doFirst { systemProperties["microej.testsuite.properties.s3.cc.activated"] = "true" + systemProperties["microej.testsuite.properties.s3.cc.thread.period"] = "15" } } } @@ -263,7 +277,7 @@ This requires to: - Have a VEE Port which implements the :ref:`BSP Connection `. - Have a device connected to your workstation both for programming the Executable and getting the output traces. Consult your VEE Port specific documentation for setup. -- Start the :ref:`tool_serial_to_socket` tool if the VEE Port does not redirect execution traces. +- Start the :ref:`sdk6_tool_serial_to_socket` tool if the VEE Port does not redirect execution traces. The configuration is similar to the one used to execute a testsuite on the Simulator. @@ -314,10 +328,10 @@ The properties are: - ``microej.testsuite.properties.microejtool.deploy.name``: name of the tool used to deploy the Executable to the board. It is required. It is generally set to ``deployToolBSPRun``. - ``microej.testsuite.properties.launch.test.trace.file``: enables the redirection of the traces in file. If the VEE Port does not have this capability, - the :ref:`tool_serial_to_socket` tool must be used to redirect the traces to a socket. -- ``microej.testsuite.properties.testsuite.trace.ip``: TCP/IP address used by the :ref:`tool_serial_to_socket` tool to redirect traces from the board. + the :ref:`sdk6_tool_serial_to_socket` tool must be used to redirect the traces to a socket. +- ``microej.testsuite.properties.testsuite.trace.ip``: TCP/IP address used by the :ref:`sdk6_tool_serial_to_socket` tool to redirect traces from the board. This property is only required if the VEE Port does not redirect execution traces. -- ``microej.testsuite.properties.testsuite.trace.port``: TCP/IP port used by the :ref:`tool_serial_to_socket` tool to redirect traces from the board. +- ``microej.testsuite.properties.testsuite.trace.port``: TCP/IP port used by the :ref:`sdk6_tool_serial_to_socket` tool to redirect traces from the board. This property is only required if the VEE Port does not redirect execution traces. Any other property can be passed to the Test Engine by prefixing it by ``microej.testsuite.properties.``. @@ -695,11 +709,14 @@ Inject Application Options For a Specific Test ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to define an Application Option for a specific test, -it must set in a file with the same name as the generated test case file, -but with the ``.properties`` extension instead of the ``.java`` extension. +it must be set in a file with the same name as the test case file, +but with the ``.properties`` extension instead of the ``.java`` extension. The file must be put in the ``src/test/resources`` folder and within the same package than the test file. -For example, to inject a Application Option for the test class ``com.mycompany.MyTest``, -it must be set in a file named ``src/test/resources/com.mycompany/MyTest.properties``. + +For example, to inject an Application Option for the test class ``MyTest`` located in the ``com.mycompany`` package, +a ``MyTest.properties`` file must be created. Its path must be: ``src/test/resources/com/mycompany/MyTest.properties``. + +Application Options defined in this file do not require the ``microej.testsuite.properties.`` prefix. .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free diff --git a/SDK6UserGuide/tools.rst b/SDK6UserGuide/tools.rst index 711f701f4..6903137dc 100644 --- a/SDK6UserGuide/tools.rst +++ b/SDK6UserGuide/tools.rst @@ -61,6 +61,7 @@ The following sections describe the IDE tools and their options: heapAnalyzer ../ApplicationDeveloperGuide/UI/MicroUI/fontDesigner localDeployTool + serialToSocketTransmitter nullAnalysis .. diff --git a/SDK6UserGuide/troubleshooting.rst b/SDK6UserGuide/troubleshooting.rst index 19218b631..48d07c16a 100644 --- a/SDK6UserGuide/troubleshooting.rst +++ b/SDK6UserGuide/troubleshooting.rst @@ -72,7 +72,7 @@ If this kind of message appears when resolving plugins or modules dependencies: .. code:: console * What went wrong: - Plugin [id: 'com.microej.gradle.application', version: '0.16.0'] was not found in any of the following sources: + Plugin [id: 'com.microej.gradle.application', version: '0.18.0'] was not found in any of the following sources: or this kind: @@ -291,6 +291,29 @@ Back in the Gradle task view: However you can configure your IDE to automatically reload your project. Refer to the :ref:`sdk_6_howto_gradle_autoreloading` section for more information. +Code Detected as Unreachable in IntelliJ +---------------------------------------- + +When opening MicroEJ project with IntelliJ ``2024.1``, code is displayed in grey (dead code style) after a call to a MicroEJ Foundation API. + +.. figure:: images/dead_code.png + :alt: Unreachable code is displayed in grey in IntelliJ + :align: center + :scale: 100% + +This happens because Foundation API dependencies do not include implementation code but only throw ``RuntimeException``. IntelliJ thus infers +that the code that comes after is unreachable. + +The detection of unreachable code can be disabled by going in :guilabel:`Settings...` > :guilabel:`Editor` > :guilabel:`Inspections` +and unchecking the option :guilabel:`Unreachable code` in :guilabel:`Java` > :guilabel:`Probable bugs`. + +.. figure:: images/unreachable_code_setings.png + :alt: Disable unreachable code detection in settings + :align: center + :scale: 70% + +You can also disable unreachable code detection locally by using ``@SuppressWarnings("UnreachableCode")`` on the method or on the class. + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDKUserGuide/heapAnalyzer.rst b/SDKUserGuide/heapAnalyzer.rst index c095ce3bf..dc040de1b 100644 --- a/SDKUserGuide/heapAnalyzer.rst +++ b/SDKUserGuide/heapAnalyzer.rst @@ -86,39 +86,126 @@ MicroEJ environment. +-----------------------+---------------+-------------------------------+ Heap Dumper ------------ +------------ -When the Heap Dumper option is activated, the garbage collector process -ends by performing a dump file that represents a snapshot of the heap at -this moment. To generate such dump files, you must explicitly call -the ``System.gc()`` method in your code. +The Heap Dumper generates ``.heap`` files. There are two implementations: -The heap dump file contains the list of all instances of both class and -array types that exist in the heap. For each instance, it records: +1. **Integrated with the Simulator**: Dumps ``.heap`` files directly from the Java heap. +2. **Heap Dumper Tool**: Generates ``.heap`` files from ``.hex`` files, which must be retrieved from the device using tools like GDB. -- the time at which the instance was created +Heap dumps should be performed after a call to `System.gc()`_ to exclude discardable objects. -- the thread that created it +Simulator +~~~~~~~~~ -- the method that created it +To generate a Heap dump of an application running on the Simulator: -For instances of class types, it also records: +1. Set the ``s3.inspect.heap`` application property to ``true``. +2. Update your application code to call the `System.gc()`_ method where you need a Heap dump. +3. Run the application on the Simulator. -- the class +When the `System.gc()`_ method is called: -- the values in the instance’s non-static fields +- If called from the application, the ``.heap`` file is generated in the ``build/output//heapDump/`` folder of the project, where ```` is the Fully Qualified Name of the application's main class, e.g., ``com.mycompany.Main``. +- If called from a test class, the ``.heap`` file is generated in the ``build/testsuite/output//bin//heapDump/`` folder of the project, where ```` is the Fully Qualified Name of the generated main class and ```` is the test execution date, e.g., ``build/testsuite/output/20240625-1605-24/bin/com.mycompany._AllTests_MyTest/heapDump/``. -For instances of array types, it also records: +Device +~~~~~~ -- the type of the contents of the array +To generate a Heap dump of an application running on a device: -- the contents of the array +1. Update your application code to call the `System.gc()`_ method where you need a Heap dump. +2. Build the executable and deploy it on the device. +3. Start a debug session. +4. Add a breakpoint to the ``LLMJVM_on_Runtime_gc_done`` Core Engine hook. This function is called by the Core Engine when the `System.gc()`_ method is done. Alternatively, for out of memory errors, add a breakpoint to the ``LLMJVM_on_OutOfMemoryError_thrown`` Core Engine hook. +5. Resume execution until the breakpoint is reached. You are now ready to dump the memory. -For each referenced class type, it records the values in the static -fields of the class. +.. note:: + + Core Engine hooks may be inlined by the third-party linker. If the symbol is not accessible to the debugger, declare them in your VEE Port: + + .. code:: c + + void LLMJVM_on_Runtime_gc_done(){ + //No need to add code to the function + } + + void LLMJVM_on_OutOfMemoryError_thrown(){ + //No need to add code to the function + } + +Retrieve the ``.hex`` file from the device +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are in a Mono-Sandbox context, you only need to dump the Core Engine heap section. Example GDB commands: + +.. code-block:: console + + b LLMJVM_on_Runtime_gc_done + b LLMJVM_on_OutOfMemoryError_thrown + continue + dump ihex memory heap.hex &_java_heap_start &_java_heap_end + +You now have the ``.hex`` file and need to extract the Heap dump. + +In a Multi-Sandbox context, additionally dump the following sections: + +- Installed features table: + + .. code-block:: console + + dump ihex memory &java_features_dynamic_start &java_features_dynamic_end +- Installed features sections specific to your VEE Port, depending on the `LLKERNEL implementation `: + + .. code-block:: console + + dump ihex memory -.. include:: heapdumper_use.rst +To simplify the dump commands, consider: + +- Dumping the entire memory where MicroEJ runtime and code sections are linked. +- Generating the :ref:`VEE memory dump script ` to dump all required sections. + +Convert ``.hex`` dump to ``.heap`` dump +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To convert the Heap dump from ``.hex`` to ``.heap``, use the Heap Dumper tool. + +The Heap Dumper should be available in your VEE Port and can be configured and executed from the SDK Run Configurations. + +From the SDK top menu, go to ``Run`` > ``Run Configurations...`` + +1. Right-click on ``MicroEJ Tool`` and select ``New Configuration``. + +2. Configure the ``Execution`` tab: + + 1. Set the tool name, e.g., ``Convert Hex to Heap``. + 2. Select the platform in the ``Target`` > ``Platform`` field. + 3. Select the ``Heap Dumper`` tool from the ``Execution`` > ``Settings`` list. + 4. Set the ``Output folder`` path, where the ``.heap`` file will be generated. + + .. figure:: images/heapdumper_options/tool_heapdumper_execution_tab.png + :scale: 50% + :align: center + + + +3. Switch to the ``Configuration`` tab and configure it: + + 1. Set the path to the firmware executable ELF file. + 2. Add the full path of application files with debug information (``.fodbg`` files). + 3. Set the full path of the heap memory dump, in Intel Hex format. + 4. Add the full path of additional memory files in Intel Hex format (installed feature areas, dynamic features table, etc.). + 5. Set the heap file output name, e.g., ``application.heap``. + + .. figure:: images/heapdumper_options/tool_heapdumper_config_tab.png + :scale: 50% + :align: center + +4. Finally, click ``Apply`` and ``Run``. + +Now you can open the generated ``.heap`` file in the Heap Viewer. .. _heapviewer: @@ -398,6 +485,8 @@ and new heap dumps, and highlights any differences between the values. Instance Fields Comparison view +.. _System.gc(): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/System.html#gc-- + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDKUserGuide/heapdumper_use.rst b/SDKUserGuide/heapdumper_use.rst deleted file mode 100644 index 7409ab09e..000000000 --- a/SDKUserGuide/heapdumper_use.rst +++ /dev/null @@ -1,78 +0,0 @@ -Category: Heap Dumper -~~~~~~~~~~~~~~~~~~~~~ - - -.. figure:: images/heapdumper_options/img1.png - :scale: 100% - :align: center - -Group: Application -^^^^^^^^^^^^^^^^^^ - -Option(browse): Executable file -''''''''''''''''''''''''''''''' - - -*Option Name*: ``application.filename`` - -*Default value*: ``(empty)`` - -*Description*: - -Specify the full path of a full linked ELF file. - -Option(list): Feature files -''''''''''''''''''''''''''' - -*Option Name*: ``additional.application.filenames`` - -*Default value*: ``(empty)`` - -*Description*: - -Specify the full path of Feature files with debug information (``.fodbg`` files). - -Group: Memory -^^^^^^^^^^^^^ - -Option(browse): Heap memory file -'''''''''''''''''''''''''''''''' - -*Option Name*: ``heap.filename`` - -*Default value*: ``(empty)`` - -*Description*: - -Specify the full path of heap memory dump, in Intel Hex format. - -Option(list): Memory files -'''''''''''''''''''''''''' - -*Option Name*: ``additional.memory.filenames`` - -*Default value*: ``(empty)`` - -*Description*: - -Specify the full path of additional memory files in Intel Hex format (Installed Feature areas, -Dynamic Features table, ...). - -Group: Output -^^^^^^^^^^^^^ - -Option(text): Heap file name -'''''''''''''''''''''''''''' - -*Option Name*: ``output.name`` - -*Default value*: ``application.heap`` - - - -.. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification - is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and - copyrights are the property of their respective owners. diff --git a/Tutorials/tutorialCreateIARImage.rst b/SDKUserGuide/howtos/createIARImage.rst similarity index 87% rename from Tutorials/tutorialCreateIARImage.rst rename to SDKUserGuide/howtos/createIARImage.rst index 7147f64f2..7214f51de 100644 --- a/Tutorials/tutorialCreateIARImage.rst +++ b/SDKUserGuide/howtos/createIARImage.rst @@ -1,9 +1,9 @@ -.. _tutorials_create_iar_image: +.. _sdk_5_howto_create_iar_image: -Add IAR to MicroEJ SDK Docker Image -=================================== +How To Add IAR to MICROEJ SDK Docker Image +========================================== -This document presents how to create a Dockerfile with `MicroEJ SDK version 5.x `_ and `Cross-platform Build Tools for Arm `_ to build a MicroEJ application. +This document presents how to create a Dockerfile with `MICROEJ SDK version 5.x `_ and `Cross-platform Build Tools for Arm `_ to build a MicroEJ application. You can use this image in your automated CI. @@ -12,7 +12,7 @@ Prerequisites * A recent version of IAR BXARM and its user licence. -This tutorial was tested with MicroEJ SDK ``5.8.1-jdk11``, IAR ``9.30.1``, and Docker ``24.0.6``. +This tutorial was tested with MICROEJ SDK ``5.8.1-jdk11``, IAR ``9.30.1``, and Docker ``24.0.6``. Create the Dockerfile --------------------- @@ -23,7 +23,7 @@ Here is our final Dockerfile. We will explain each specific step below. :language: dockerfile #. In a new directory create a file named ``Dockerfile``. -#. We use MicroEJ SDK base image, they are available on `docker hub `_. In your Dockerfile add this code: +#. We use MICROEJ SDK base image, they are available on `docker hub `_. In your Dockerfile add this code: .. code-block:: dockerfile diff --git a/SDKUserGuide/howtos/index.rst b/SDKUserGuide/howtos/index.rst new file mode 100644 index 000000000..6a7e560ca --- /dev/null +++ b/SDKUserGuide/howtos/index.rst @@ -0,0 +1,17 @@ +.. _sdk_5_howto_guides: + +How-to Guides +============= + +.. toctree:: + :maxdepth: 1 + + createIARImage + + +.. + | Copyright 2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/Tutorials/resources/IARDockerfile b/SDKUserGuide/howtos/resources/IARDockerfile similarity index 100% rename from Tutorials/resources/IARDockerfile rename to SDKUserGuide/howtos/resources/IARDockerfile diff --git a/SDKUserGuide/images/heapdumper_options/img1.png b/SDKUserGuide/images/heapdumper_options/img1.png deleted file mode 100644 index 64612b5f0..000000000 Binary files a/SDKUserGuide/images/heapdumper_options/img1.png and /dev/null differ diff --git a/SDKUserGuide/images/heapdumper_options/tool_heapdumper_config_tab.png b/SDKUserGuide/images/heapdumper_options/tool_heapdumper_config_tab.png new file mode 100644 index 000000000..5fd50a654 Binary files /dev/null and b/SDKUserGuide/images/heapdumper_options/tool_heapdumper_config_tab.png differ diff --git a/SDKUserGuide/images/heapdumper_options/tool_heapdumper_execution_tab.png b/SDKUserGuide/images/heapdumper_options/tool_heapdumper_execution_tab.png new file mode 100644 index 000000000..30563ce70 Binary files /dev/null and b/SDKUserGuide/images/heapdumper_options/tool_heapdumper_execution_tab.png differ diff --git a/SDKUserGuide/images/sentinel_architecture.png b/SDKUserGuide/images/sentinel_architecture.png new file mode 100644 index 000000000..75e5d3c52 Binary files /dev/null and b/SDKUserGuide/images/sentinel_architecture.png differ diff --git a/SDKUserGuide/images/sentinel_rte_client_installed_license.png b/SDKUserGuide/images/sentinel_rte_client_installed_license.png new file mode 100644 index 000000000..3c0ac27e6 Binary files /dev/null and b/SDKUserGuide/images/sentinel_rte_client_installed_license.png differ diff --git a/SDKUserGuide/images/sentinel_rte_client_remote_config.png b/SDKUserGuide/images/sentinel_rte_client_remote_config.png new file mode 100644 index 000000000..b59d5fe06 Binary files /dev/null and b/SDKUserGuide/images/sentinel_rte_client_remote_config.png differ diff --git a/SDKUserGuide/images/sentinel_rte_server_get_fingerprint.png b/SDKUserGuide/images/sentinel_rte_server_get_fingerprint.png new file mode 100644 index 000000000..e3a664ad1 Binary files /dev/null and b/SDKUserGuide/images/sentinel_rte_server_get_fingerprint.png differ diff --git a/SDKUserGuide/images/sentinel_rte_server_installed_license.png b/SDKUserGuide/images/sentinel_rte_server_installed_license.png new file mode 100644 index 000000000..64dfa84c6 Binary files /dev/null and b/SDKUserGuide/images/sentinel_rte_server_installed_license.png differ diff --git a/SDKUserGuide/index.rst b/SDKUserGuide/index.rst index 4b4995031..a94710616 100644 --- a/SDKUserGuide/index.rst +++ b/SDKUserGuide/index.rst @@ -67,6 +67,7 @@ The SDK is licensed under the :ref:`SDK End User License Agreement (EULA) Detected dongle UID: XXXXXXXX. - [DEBUG] => Dongle UID has valid MicroEJ data: XXXXXXXX (only the first one is listed). - [DEBUG] => Detected MicroEJ License XXXXX-XXXXX-XXXXX-XXXXX - valid until YYYY-MM-DD. - [DEBUG] ===== SUCCESS ===== + with ``OS_NAME`` set to ``Windows64`` for Windows OS, ``Linux64`` for Linux OS, ``Mac`` for macOS x86_64 (Intel chip) or ``MacA64`` for macOS aarch64 (M1 chip). + +If your USB dongle has been properly activated, you should get the following output: + +.. code:: console + [DEBUG] ===== MicroEJ Dongle Debug Tool ===== + [DEBUG] => Detected dongle UID: XXXXXXXX. + [DEBUG] => Dongle UID has valid MicroEJ data: XXXXXXXX (only the first one is listed). + [DEBUG] => Detected MicroEJ License XXXXX-XXXXX-XXXXX-XXXXX - valid until YYYY-MM-DD. + [DEBUG] ===== SUCCESS ===== .. _production_license_linux: diff --git a/SDKUserGuide/mmm.rst b/SDKUserGuide/mmm.rst index 114246feb..d0246a0ee 100644 --- a/SDKUserGuide/mmm.rst +++ b/SDKUserGuide/mmm.rst @@ -457,6 +457,10 @@ The ``mmm`` tool can run on any supported :ref:`Operating Systems `_ such as `Git BASH `_ using the bash script ``mmm``. - on macOS and Linux distributions using the bash script ``mmm``. +.. warning:: + + When copying a build kit from one system to another, make sure to delete the cache of the buildtype repository (``/microej-build-repository/cache``) which may contain absolute paths. + The build repository (``microej-build-repository`` directory) contains scripts and tools for building modules. It is specific to a SDK version and shall not be modified by default. The module repository (``microej-module-repository`` directory) contains a default :ref:`mmm_settings_file` for importing modules from :ref:`central_repository` and this local repository (modules that are locally built will be published to this directory). @@ -943,6 +947,23 @@ Make sure it is one of the following ones: - ``build-microej-javalib``, with version ``4.2.0`` or higher - ``build-firmware-singleapp``, with version ``1.3.0`` or higher +Could not load SWT library +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +| Trying to use MMM Build Kit on headless system may lead to this error when building a VEE Port. +| To fix this on Ubuntu (tested on 22.04), install the ``libwebkit2gtk-4.0-37`` package. + +.. note:: + + Also see our full Docker image configuration: https://github.com/MicroEJ/Tool-SDK-Docker/blob/67a9f4397a9c1d5608a244e2778c0cfecc5c6113/5.8.2-jdk11/Dockerfile + +systemmicroui.xml:47: Terminated with errors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +| Trying to build a VEE Port may lead to an "Internal limits reached" for which the log file contains this error. +| This is caused by using an incompatible JDK distribution (such as ``openjdk-11-jdk`` Ubuntu distribution). +| To fix this, change your JDK distribution. See :ref:`recommended JDK distributions `. + .. _mmm_former_sdk_5_2: Former SDK Versions (lower than 5.2.0) diff --git a/SDKUserGuide/sandboxedAppFirstApplication.rst b/SDKUserGuide/sandboxedAppFirstApplication.rst index d6330f092..fef12f15e 100644 --- a/SDKUserGuide/sandboxedAppFirstApplication.rst +++ b/SDKUserGuide/sandboxedAppFirstApplication.rst @@ -104,9 +104,20 @@ See :ref:`mmm` for more information. The dependencies must contain at least a module containing the ``ej.kf.FeatureEntryPoint`` class, for example the KF library: -.. code:: xml +.. tabs:: - + .. tab:: SDK 6 + + .. code-block:: java + + implementation("ej.api:kf:1.7.0") + + .. tab:: SDK 5 + + .. code-block:: xml + + + .. diff --git a/SDKUserGuide/sdkChangeLog.rst b/SDKUserGuide/sdkChangeLog.rst index 014f950b9..b0e9d7934 100644 --- a/SDKUserGuide/sdkChangeLog.rst +++ b/SDKUserGuide/sdkChangeLog.rst @@ -177,6 +177,39 @@ SDK Distribution Changelog SDK Changelog ------------- +.. _changelog-5.9.0: + +[5.9.0] - 2024-07-23 +~~~~~~~~~~~~~~~~~~~~ + +General +""""""" + +- Hide MicroEJ project wizards when SDK 5 is installed in an Eclipse distribution including SDK 6 plugins. + +MicroEJ Module Manager +"""""""""""""""""""""" + +General +^^^^^^^ + +- Upgraded Testsuite Engine to version 5.8.1 to separate test cases in the testsuite reports and escape console output in HTML report to prevent code injection. + +Build Types +^^^^^^^^^^^ + +- Set default Java test compile version to 1.8 for ``build-std-javalib`` and ``build-microej-mock`` build types. + +- New build types added: + + - build-application#9.3.0 + - build-firmware-singleapp#2.4.0 + - build-microej-javaimpl#5.3.0 + - build-microej-javalib#6.3.0 + - build-microej-mock#2.2.1 + - build-microej-testsuite#4.3.0 + - build-std-javalib#3.3.1 + .. _changelog-5.8.2: [5.8.2] - 2024-01-31 @@ -1201,6 +1234,28 @@ Skeletons Build Types per SDK ------------------- +- SDK 5.9.0 + + - build-addon-processor#2.2.0 + - build-application#9.3.0 + - build-artifact-repository#3.4.0 + - build-custom#2.2.0 + - build-firmware-customizer#3.2.0 + - build-firmware-multiapp#8.2.0 + - build-firmware-singleapp#2.4.0 + - build-izpack#3.3.0 + - build-microej-extension#2.2.0 + - build-microej-javaapi#5.2.0 + - build-microej-javaimpl#5.3.0 + - build-microej-javalib#6.3.0 + - build-microej-mock#2.2.1 + - build-microej-ri#3.2.0 + - build-microej-testsuite#4.3.0 + - build-product-java#2.2.0 + - build-runtime-api#4.1.0 + - build-std-javalib#3.3.1 + - microej-meta-build#3.0.0 + - SDK 5.8.2 - build-addon-processor#2.2.0 diff --git a/SDKUserGuide/systemRequirements.rst b/SDKUserGuide/systemRequirements.rst index 07303ca02..3c9303d4b 100644 --- a/SDKUserGuide/systemRequirements.rst +++ b/SDKUserGuide/systemRequirements.rst @@ -10,7 +10,12 @@ System Requirements - **Operating Systems :** - Windows 11, Windows 10, Windows 8.1 or Windows 8 - - Linux distributions (tested on Ubuntu 18.04, 20.04 and 22.04) - As of SDK Distribution ``20.10`` (based on Eclipse 2020-06), Ubuntu 16.04 is not supported. + - Linux distributions (tested on Ubuntu 18.04, 20.04 and 22.04) + + - As of SDK Distribution ``20.10`` (based on Eclipse 2020-06), Ubuntu 16.04 is not supported. + - For headless installations, the ``libwebkit2gtk-4.0-37`` package is required additionally. + - The OpenJDK distribution from Ubuntu is not supported. The Eclipse Temurin distribution is recommended. + - macOS x86_64 with Intel chip (tested on version 10.13 High Sierra, 10.14 Mojave) - macOS aarch64 with M1 chip (tested on version 12.0.1 Monterey), from SDK Distribution ``22.06`` (requires :ref:`Architecture 7.18.0 or higher `) diff --git a/Tutorials/images/tuto_microej_cli_artifactory_preview.PNG b/Tutorials/images/tuto_microej_cli_artifactory_preview.PNG deleted file mode 100644 index 6cc2b709b..000000000 Binary files a/Tutorials/images/tuto_microej_cli_artifactory_preview.PNG and /dev/null differ diff --git a/Tutorials/images/tuto_microej_cli_jenkins_build.PNG b/Tutorials/images/tuto_microej_cli_jenkins_build.PNG deleted file mode 100644 index 6a41c746d..000000000 Binary files a/Tutorials/images/tuto_microej_cli_jenkins_build.PNG and /dev/null differ diff --git a/Tutorials/images/tuto_microej_cli_jenkins_parameter.PNG b/Tutorials/images/tuto_microej_cli_jenkins_parameter.PNG deleted file mode 100644 index 400f40cd9..000000000 Binary files a/Tutorials/images/tuto_microej_cli_jenkins_parameter.PNG and /dev/null differ diff --git a/Tutorials/images/tuto_microej_platform_how_to_select_modules.PNG b/Tutorials/images/tuto_microej_platform_how_to_select_modules.PNG deleted file mode 100644 index 2da7d34f4..000000000 Binary files a/Tutorials/images/tuto_microej_platform_how_to_select_modules.PNG and /dev/null differ diff --git a/Tutorials/images/tuto_microej_trace_constant.png b/Tutorials/images/tuto_microej_trace_constant.png deleted file mode 100644 index a4ecf2884..000000000 Binary files a/Tutorials/images/tuto_microej_trace_constant.png and /dev/null differ diff --git a/Tutorials/images/tuto_microej_trace_property.png b/Tutorials/images/tuto_microej_trace_property.png deleted file mode 100644 index a7dee51ca..000000000 Binary files a/Tutorials/images/tuto_microej_trace_property.png and /dev/null differ diff --git a/Tutorials/index.rst b/Tutorials/index.rst index 51cfd0df4..605511a3e 100644 --- a/Tutorials/index.rst +++ b/Tutorials/index.rst @@ -7,23 +7,15 @@ Tutorials :maxdepth: 1 tutorialUnderstandMicroEJFirmwareBuild - tutorialCreateCustomPlatform tutorialCreateFirmwareFromScratch - tutorialCreateIARImage tutorialCreatePlatformBuildAndRunScripts tutorialSetupBuildUsingJenkinsAndArtifactory tutorialImproveCodeQuality tutorialOptimizeMemoryFootprint - tutorialExploreDataSerializationFormats - tutorialInstrumentJavaCodeForLogging - tutorialRunATestSuiteOnDevice tutorialImplementABlockingNativeMethodWithSNI tutorialDiscoverEmbeddedDebuggingTechniques getStartedWithGUI/index tutorialValidateGUIs - tutorialSoftwareRobot - tutorialTextOverflow - tutorialAppendEmojisToVectorFont .. | Copyright 2021-2024, MicroEJ Corp. Content in this space is free diff --git a/Tutorials/tutorialCreateCustomPlatform.rst b/Tutorials/tutorialCreateCustomPlatform.rst deleted file mode 100644 index c711dcbb9..000000000 --- a/Tutorials/tutorialCreateCustomPlatform.rst +++ /dev/null @@ -1,154 +0,0 @@ -Create a MicroEJ Platform for a Custom Device -============================================= - -Introduction ------------- - -A MicroEJ Architecture is a software package that includes the 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. - -A MicroEJ Platform is a MicroEJ Architecture port for a custom device. -It contains the MicroEJ configuration and the BSP (C source files). - -MicroEJ Corp. provides MicroEJ Evaluation Architectures at https://repository.microej.com/modules/, -and MicroEJ Platform demo projects for various evaluation boards at https://repository.microej.com/index.php?resource=JPF. - -We recommend reading the :ref:`vee` section to get an overview of MicroEJ Firmware build flow. - -The following document assumes the reader is familiar with the :ref:`vee-porting-guide`. - -Each MicroEJ Platform is specific to: - -* a MicroEJ Architecture (MCU ISA and C compiler) -* an optional RTOS (e.g. FreeRTOS - note: the MicroEJ OS can run bare metal) -* a device: the OS bring up code that is device specific (e.g. the MCU specific code/IO/RAM/Clock/Middleware… configurations) - -In this document we will address the following items: - -* MicroEJ Platform Configuration project (in MicroEJ SDK) -* MicroEJ Simulator (in MicroEJ SDK) -* Platform BSP (in a C IDE/Compiler like GCC/KEIL/IAR) - -The MicroEJ Platform relies on C drivers (aka low level LL drivers) for each of the platform feature. -These drivers are implemented in the platform BSP project. This project is edited in the C compiler IDE/dev environment (e.g. KEIL, GCC, IAR). -E.g. the MicroUI library LED feature will require a ``LLUI_LED.c`` that implements the native on/off IO drive. - -The following sections explain how to create a MicroEJ Platform for a custom device starting from an existing MicroEJ Platform project -whether it is configured for the same MCU/RTOS/C Compiler or not. - -In the following, we assume that the new device hardware is validated and at least a trace output is available. -It is also a good idea to run basic hardware tests like: - -* Internal and external flash programming and verification -* RAM 8/16/32 -bit read/write operations (internal and external if any) -* EEMBC Coremark benchmark to verify the CPU/buses/memory/compiler configuration -* See the `Platform Qualification Tools`_ used to qualify MicroEJ Platforms. - -.. _Platform Qualification Tools: https://github.com/MicroEJ/VEEPortQualificationTools - -A MicroEJ Platform Project is already available for the same MCU/RTOS/C Compiler --------------------------------------------------------------------------------- - -This is the fastest way: the MicroEJ Platform is usually provided for a silicon vendor evaluation board. -Import this platform in MicroEJ SDK. - -As the MCU, RTOS and compiler are the same, only the device specific code needs to be changed (external RAM, external oscillator, communication interfaces). - -Platform -:::::::: - -In the SDK - -* modify the ``.platform`` from the MicroEJ Platform (``xxx-configuration`` project) to match the device features and its associated configuration (e.g. ``UI->Display``). - - .. image:: images/tuto_microej_platform_how_to_select_modules.PNG - - More details on available modules can be found in the :ref:`vee-porting-guide`. - - -BSP -::: - -Required actions: - -* modify the BSP C project to match the device specification - - * edit the scatter file/link options - * edit the compilation options - -* create/review/change the platform Low Level C drivers. - They must match the device components and the MCU IO pin assignment - - .. note:: - - A number of ``LL*.h`` files are referenced from the project. - Implement the function prototypes declared there so that the JVM can delegate the relevant operations to the provided BSP C functions. - -Simulator -::::::::: - -In the SDK - -* modify the existing Simulator Front Panel ``xxx-fp`` project - -A MicroEJ Platform Project is not available for the same MCU/RTOS/C Compiler ----------------------------------------------------------------------------- - -Look for an available MicroEJ Platform that will match in order of priority: - -* same MCU part number -* same RTOS -* same C compiler - -At this point, consider either to modify the closest MicroEJ Platform - -* In the SDK: modify the platform configuration. -* in the C IDE: start from an empty project that match with the MCU. - -Or to start from scratch a new MicroEJ Platform - -* In the SDK: create the MicroEJ Platform and refer to the selected MicroEJ Platform as a model for implementation. (refer to :ref:`platform_configuration_creation`) -* in the C IDE: start from an empty project and implement the drivers of each of the LL drivers API. - - Make sure to link with: - - * the ``microejruntime.a`` that runs the JVM for the MCU Architecture - * the ``microejapp.o`` that contains the compiled Java application - -MCU -::: - -The MCU specific code can be found: - -* in the C project IDE properties -* in the linker file -* the IO configuration -* in the low level driver (these drivers are usually provided by the silicon vendor) - -RTOS -:::: - -The LL driver is named ``LLMJVM_RTOS.c/.h``. Modify this file to match the selected RTOS. - -C Compiler -:::::::::: - -The BSP project is provided for a specific compiler (that matches the selected platform architecture). -Start a new project with the compiler IDE that includes the LL drivers and start the MicroEJ Platform in the ``main()`` function. - -Platform Validation -------------------- - -Use the `Platform Qualification Tools`_ to qualify the MicroEJ Platform built. - -Further Assistance Needed -------------------------- - -Please note that porting MicroEJ to a new device is also something that is part of our engineering services. Consider contacting `our sales team `_ to request a quote. - -.. - | Copyright 2021-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification - is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and - copyrights are the property of their respective owners. \ No newline at end of file diff --git a/Tutorials/tutorialCreatePlatformBuildAndRunScripts.rst b/Tutorials/tutorialCreatePlatformBuildAndRunScripts.rst index 30330abdf..6a775ebb4 100644 --- a/Tutorials/tutorialCreatePlatformBuildAndRunScripts.rst +++ b/Tutorials/tutorialCreatePlatformBuildAndRunScripts.rst @@ -380,7 +380,7 @@ Going Further - More about build and run scripts in :ref:`bsp_connection_build_script` and :ref:`bsp_connection_run_script` sections - Some build scripts examples from `Platform Qualification Tools`_ -- Perform the :ref:`tutorial_run_test_suite_on_device` tutorial to learn how to run an automated testsuite +- Follow the :ref:`run_test_suite_on_device` documentation to learn how to run an automated testsuite - Perform the :ref:`tutorial_setup_automated_build_using_jenkins_and_artifactory` tutorial to learn how to automate the build of a MicroEJ Platform module .. _Platform Qualification Tools: https://github.com/MicroEJ/VEEPortQualificationTools/tree/master/framework/platform/scripts diff --git a/Tutorials/tutorialDiscoverEmbeddedDebuggingTechniques.rst b/Tutorials/tutorialDiscoverEmbeddedDebuggingTechniques.rst index 2defdb230..b2d2889e2 100644 --- a/Tutorials/tutorialDiscoverEmbeddedDebuggingTechniques.rst +++ b/Tutorials/tutorialDiscoverEmbeddedDebuggingTechniques.rst @@ -96,7 +96,7 @@ When an application has issues, the first step is to understand what is happenin + currentState.toString() + "."); } -Please refer to the tutorial :ref:`tutorial_instrument_java_code_for_logging` for a comparison of these libraries. +Please refer to the :ref:`codeInstrumentationForLogging` documentation for a comparison of these libraries. .. _Trace Library: https://repository.microej.com/javadoc/microej_5.x/apis/ej/trace/Tracer.html .. _Message Library: https://repository.microej.com/javadoc/microej_5.x/apis/ej/util/message/basic/BasicMessageLogger.html diff --git a/Tutorials/tutorialSetupBuildUsingJenkinsAndArtifactory.rst b/Tutorials/tutorialSetupBuildUsingJenkinsAndArtifactory.rst index 16562c8c1..ae3641a7c 100644 --- a/Tutorials/tutorialSetupBuildUsingJenkinsAndArtifactory.rst +++ b/Tutorials/tutorialSetupBuildUsingJenkinsAndArtifactory.rst @@ -4,8 +4,6 @@ Setup an Automated Build using Jenkins and Artifactory ====================================================== -This tutorial explains how to setup an environment for automating :ref:`MicroEJ Module build ` and deployment using `Jenkins `_, `JFrog Artifactory `_ and a `Git plateform `_ (you can also use Gitlab or Github for example). - Such environment setup facilitates continuous integration (CI) and continuous delivery (CD), which improves productivity across your development ecosystem, by automatically: @@ -14,7 +12,7 @@ by automatically: * reproducing builds * archiving binary modules -The tutorial should take 1 hour to complete. +This guide should take 1 hour to complete. Intended Audience @@ -23,10 +21,10 @@ Intended Audience The audience for this document is engineers who are in charge of integrating :ref:`MicroEJ Module Manager (MMM) ` to their continuous integration environment. -In addition, this tutorial should be of interest to all developers +In addition, this document should be of interest to all developers wishing to understand how MicroEJ works with headless module builds. -For those who are only interested by command line module build, consider using the :ref:`MMM Command Line Interface `. +For those who are only interested in command line module build, consider using the :ref:`MMM Command Line Interface `. Introduction ------------ @@ -47,7 +45,7 @@ The overall build and deployment flow of a module can be summarized as follows: Prerequisites ------------- -* `MicroEJ SDK 5 `_ ``5.8.1`` or higher. +* `MICROEJ SDK 5 `_ ``5.8.1`` or higher. * `Docker and Docker Compose V2 `_ on Linux, Windows or Mac * Git ``2.x`` installed, with Git executable in path. We recommend installing Git Bash if your operating system is Windows (``_). @@ -105,7 +103,7 @@ Get a Module Repository A Module Repository is a portable ZIP file that bundles a set of modules for extending the MicroEJ development environment. Please consult the :ref:`Module Repository ` section for more information. -This tutorial uses the MicroEJ Central Repository, which is the Module Repository used by MicroEJ SDK to fetch dependencies when starting an empty workspace. +This tutorial uses the MicroEJ Central Repository, which is the Module Repository used by MICROEJ SDK to fetch dependencies when starting an empty workspace. It bundles Foundation Library APIs and numerous Add-On Libraries. Next step is to download a local copy of this repository: @@ -224,7 +222,7 @@ In this example, we will create a very simple module using the Sandbox Applicati For demonstration purposes, we'll create a new project and share it on a local Git bare repository. You can adapt the following sections to use an existing MicroEJ project and your own Git repository. -#. Start MicroEJ SDK. +#. Start MICROEJ SDK. #. Go to :guilabel:`File` > :guilabel:`New` > :guilabel:`Sandboxed Application Project`. #. Fill in the template fields, set :guilabel:`Project name` to ``com.example.hello-world``. @@ -248,7 +246,7 @@ In this example, we will create a very simple module using the Sandbox Applicati :align: center .. note:: - For more details about MicroEJ Applications development, refer to the :ref:`Application Developer Guide `. + For more details about Applications development, refer to the :ref:`Application Developer Guide `. Upload to your Git repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Tutorials/tutorialTextOverflow.rst b/Tutorials/tutorialTextOverflow.rst deleted file mode 100644 index 54e4c1c2d..000000000 --- a/Tutorials/tutorialTextOverflow.rst +++ /dev/null @@ -1,219 +0,0 @@ -How to Detect Text Overflow -=========================== - - -Widgets that display a text may experience text overflow when the strings are too long to fit into the available area. -It can be the case, for example, in applications that support multiple languages because widgets have to deal with texts of different lengths. - -This document presents a solution to detect such text overflows. - - -Instrumenting the Widget ------------------------- - -The goal is to check whether the text to be displayed is within the content bounds of the widget. A way to test this is to extend or modify the widget. -In this article, the widget ``MyLabel`` will extend the type `Label`_ from the Widget library, which displays a text: - -.. code-block:: java - :emphasize-lines: 3 - - import ej.widget.basic.Label; - - public class MyLabel extends Label { - - public MyLabel(String text) { - super(text); - } - } - - -.. _Label: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/basic/Label.html - -Overriding the onLaidOut() Method ---------------------------------- - -Once the position and size of a wigdet are set during the lay out process, the `onLaidOut()`_ method is called to notify the widget. -Overriding `onLaidOut()`_ of class ``MyLabel`` is a good place to check whether the text overflows or not. - -For example, the following snippet compares the text width with the available width: it will print a message if an overflow is detected. - -.. code-block:: java - :emphasize-lines: 12,13,14 - - @Override - protected void onLaidOut() { - super.onLaidOut(); - - // compute the width of the text with the specified font - final Font font = getStyle().getFont(); - final String text = getText(); - final int textWidth = font.stringWidth(text); - - // compare to the width available for the content of the widget - final int contentWidth = getContentBounds().getWidth(); - if (textWidth > contentWidth) { - System.out.println("Overflow detected:\n > Text: \"" + text + "\"\n > Width = " + textWidth + " px (available: " + contentWidth + " px)"); - } - } - -.. _onLaidOut(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#onLaidOut-- - -Testing -------- - -Here is a case where the widget size is set manually to be a little shorter than the text width: - -.. code-block:: java - :emphasize-lines: 6 - - public static void main(String[] args) { - MicroUI.start(); - Desktop desktop = new Desktop(); - Canvas canvas = new Canvas(); - // add a label with an arbitrary fixed width of 25 pixels (which is too short) - canvas.addChild(new MyLabel("Some text"), 20, 20, 25, 10); - desktop.setWidget(canvas); - desktop.requestShow(); - } - -.. image:: images/tuto_microej_bounds_check.png - :alt: Text overflow example - :align: center - -The text is cropped and the console logs that a text overflow has been detected: - -.. code-block:: console - - =============== [ Initialization Stage ] =============== - =============== [ Converting fonts ] =============== - =============== [ Converting images ] =============== - =============== [ Launching on Simulator ] =============== - Overflow detected: - > Text: "Some text" - > Width = 47 px (available: 25 px) - - -Improving the Detection ------------------------ - -To ease the correction process, it is best to add some additional debug information to locate the issue. -Let's extract the text overflow detection into a helper class, so that it is available for all classes across the application. - -The following snippet: - -* extracts the text overflow detection into the class ``MyTextHelper``. -* prints the part of the text that is displayed. -* prints the path to the widget in the widget tree to help the tester locate the affected widget in the GUI. - -.. code-block:: java - :emphasize-lines: 13,30 - - public class MyLabel extends Label { - - public MyLabel(String text) { - super(text); - } - - @Override - protected void onLaidOut() { - super.onLaidOut(); - - final Font font = getStyle().getFont(); - final String text = getText(); - MyTextHelper.checkTextOverflow(this, text, font); - } - } - - public class MyTextHelper { - - /** - * Checks whether the given text overflows for the specified widget and font. In the case where an overflow is - * detected, the method prints a message that details the error. - * - * @param widget - * the widget that displays the text. - * @param text - * the text to display. - * @param font - * the font used for drawing the text. - */ - public static void checkTextOverflow(final Widget widget, final String text, final Font font) { - final int textWidth = font.stringWidth(text); - final int contentWidth = widget.getContentBounds().getWidth(); - - if (textWidth > contentWidth) { - String displayedText = buildDisplayedText(text, font, contentWidth); - String widgetPath = buildWidgetPath(widget); - System.out.println( - "Overflow detected:\n > Text: \"" + text + "\"\n > Width = " + textWidth + " px (available: " - + contentWidth + " px) \n > Displayed: \"" + displayedText + "\"\n > Path : " + widgetPath); - } - } - - private static String buildDisplayedText(String text, Font font, int width) { - for (int i = text.length() - 1; i > 0; i--) { - if (font.substringWidth(text, 0, i) <= width) { - return text.substring(0, i); - } - } - - return ""; - } - - private static String buildWidgetPath(Widget widget) { - StringBuilder builder = new StringBuilder(); - - Widget ancestor = widget; - do { - builder.insert(0, " > " + ancestor.getClass().getSimpleName()); - ancestor = ancestor.getParent(); - } while (ancestor != null); - builder.insert(0, widget.getDesktop().getClass().getSimpleName()); - - return builder.toString(); - } - } - -When the application is launched again, the console shows more information about the text overflow: - -.. code-block:: console - - =============== [ Initialization Stage ] =============== - =============== [ Converting fonts ] =============== - =============== [ Converting images ] =============== - =============== [ Launching on Simulator ] =============== - Overflow detected: - > Text: "Some text" - > Width = 47 px (available: 25 px) - > Displayed: "Some" - > Path : Desktop > Canvas > MyLabel - - -To keep control over the extra verbosity and code size, one option is to use :ref:`BON constants ` to enable/disable this debug code at will. -In the following snippet, when the constant ``com.mycompany.check.text.overflow`` is set to ``false``, the debug code will not be embedded in the application. - -.. code-block:: java - :emphasize-lines: 2 - - public static void checkTextOverflow(final Widget widget, final String text, final Font font) { - if (Constants.getBoolean("com.mycompany.check.text.overflow")) { - final int textWidth = font.stringWidth(text); - final int contentWidth = widget.getContentBounds().getWidth(); - - if (textWidth > contentWidth) { - String displayedText = buildDisplayedText(text, font, contentWidth); - String widgetPath = buildWidgetPath(widget); - System.out.println( - "Overflow detected:\n > Text: \"" + text + "\"\n > Width = " + textWidth + " px (available: " - + contentWidth + " px) \n > Displayed: \"" + displayedText + "\"\n > Path : " + widgetPath); - } - } - } - - -.. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification - is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and - copyrights are the property of their respective owners. diff --git a/Tutorials/tutorialValidateGUIs.rst b/Tutorials/tutorialValidateGUIs.rst index 66004f827..9f8234531 100644 --- a/Tutorials/tutorialValidateGUIs.rst +++ b/Tutorials/tutorialValidateGUIs.rst @@ -252,7 +252,7 @@ Here are the steps required to use a robot in the MicroEJ environment: This simple way of automating GUI actions can be used to carry out real use cases and evaluate the results. -The :ref:`How to test a GUI application with a (software) robot` tutorial provides detailed insight into this topic. +The :ref:`How to test a GUI application with a (software) robot` tutorial provides detailed insight into this topic. Test a GUI Application with the Test Automation Tool ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/VEEPortingGuide/appendix/llapi.rst b/VEEPortingGuide/appendix/llapi.rst index 568d369de..e5a2a3e67 100644 --- a/VEEPortingGuide/appendix/llapi.rst +++ b/VEEPortingGuide/appendix/llapi.rst @@ -435,7 +435,7 @@ The parameters define one or several rectangular regions of the content that hav This function should be atomic: the implementation has to start another task or a hardware device (often a DMA) to perform the flush. As soon as the Application performs a new drawing, the Graphics Engine locks the thread. -It will automatically be unlocked when the BSP calls ``LLUI_DISPLAY_setDrawingBuffer`` at the end of the flush. +It will automatically be unlocked when the BSP calls ``LLUI_DISPLAY_setBackBuffer`` at the end of the flush. Display Characteristics ----------------------- diff --git a/VEEPortingGuide/architectureChangelog.rst b/VEEPortingGuide/architectureChangelog.rst index b855e85b0..274b32f92 100644 --- a/VEEPortingGuide/architectureChangelog.rst +++ b/VEEPortingGuide/architectureChangelog.rst @@ -34,6 +34,57 @@ specific configuration: - ``QNX65``: BlackBerry QNX 6.5 - ``QNX70``: BlackBerry QNX 7.0 +.. _changelog-8.1.1: + +[8.1.1] - 2024-06-17 +-------------------- + +Core Engine +~~~~~~~~~~~ + +- [Multi] - Fixed call to ``LLKERNEL_IMPL_freeFeature(int32_t handle)`` with handle ``0`` when an FO file is corrupted or not compatible with the Core Engine. + +Foundation Libraries +~~~~~~~~~~~~~~~~~~~~ + +- Fixed unexpected `java.lang.NullPointerException`_ when a runtime exception or a native exception occurs in a try-with-resources block, and the method `AutoCloseable.close()`_ throws an exception. +- Fixed `Throwable.getSuppressed()`_ which exposes a private mutable member. +- Fixed `Throwable.printStackTrace()`_ which does not print suppressed exceptions. +- Fixed `Throwable.printStackTrace()`_ which erroneously printed the thread name. + +.. _AutoCloseable.close(): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/AutoCloseable.html#close-- +.. _Throwable.getSuppressed(): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/Throwable.html#getSuppressed-- +.. _Throwable.printStackTrace(): https://repository.microej.com/javadoc/microej_5.x/apis/java/lang/Throwable.html#printStackTrace-- + +Integration +~~~~~~~~~~~ + +- [ESP32] Fixed copy of ``microejapp.s`` into the C project. +- Fixed properties defined in VEE Port ``release.properties`` file not passed to the SOAR. +- Fixed Virtual Device that could not override HIL options for debugging the Mock. +- Fixed build and run scripts end-of-line (EOL) characters if a Linux VEE port is built on Windows. +- Removed warning messages related to missing HIL debug options when running the Simulator. + +Simulator +~~~~~~~~~ + +- Fixed breakpoint not taken into account by IntelliJ Idea's debugger when a class is not loaded during the startup. +- Fixed boostrap thread which could be visible in the thread list when debugging. +- Fixed debugger error when clinit code takes time to execute. +- Fixed debugger stuck when stepping over another breakpoint in Eclipse. +- Fixed missing traces when debug logs are activated. + +SOAR +~~~~ + +- [Multi] - Fixed the 64 KB size limitation for Java Strings section that caused an ``AssertionError`` in the SOAR when building a Sandboxed Application. + + +Tools +~~~~~ + +- Fixed Resource Buffer Generator that keeps a lock on input files and prevents them from being deleted. + .. _changelog-8.1.0: [8.1.0] - 2023-12-22 @@ -248,9 +299,9 @@ Tools - Fixed an incorrect generation of a debug file beside the memory file when launching the Heap Dumper. - [Multi] Added Heap Dumper support for dynamically installed Features. -.. _changelog-7.20.3: +.. _changelog-7.20.5: -[maintenance/7.20.3] - 2024-02-28 +[maintenance/7.20.5] - 2024-05-24 --------------------------------- Foundation Libraries diff --git a/VEEPortingGuide/architectureReleaseNotes.rst b/VEEPortingGuide/architectureReleaseNotes.rst index 2784a0578..faa636206 100644 --- a/VEEPortingGuide/architectureReleaseNotes.rst +++ b/VEEPortingGuide/architectureReleaseNotes.rst @@ -24,8 +24,8 @@ The following table describes Foundation Libraries API versions implemented in M - Trace - Device - ECOM-COMM - * - 8.0.0 - - `1.3 `__ + * - [8.0.0-8.1.1] + - `1.3 `__ - `1.4 `__ - `1.7 `__ - `1.4 `__ @@ -34,7 +34,7 @@ The following table describes Foundation Libraries API versions implemented in M - N/A [1]_ - N/A [2]_ * - [7.17.0-7.20.1] - - `1.3 `__ + - `1.3 `__ - `1.4 `__ - `1.6 `__ - `1.4 `__ @@ -43,7 +43,7 @@ The following table describes Foundation Libraries API versions implemented in M - `1.0 `__ - `1.1 `__ * - [7.13.0-7.16.0] - - `1.3 `__ + - `1.3 `__ - `1.4 `__ - `1.5 `__ - `1.4 `__ @@ -52,7 +52,7 @@ The following table describes Foundation Libraries API versions implemented in M - `1.0 `__ - `1.1 `__ * - [7.11.0-7.12.0] - - `1.3 `__ + - `1.3 `__ - `1.4 `__ - `1.5 `__ - `1.3 `__ diff --git a/VEEPortingGuide/images/bsp-connection-cases.pptx b/VEEPortingGuide/images/bsp-connection-cases.pptx deleted file mode 100644 index 5a67b80b8..000000000 Binary files a/VEEPortingGuide/images/bsp-connection-cases.pptx and /dev/null differ diff --git a/VEEPortingGuide/images/font-external-font-heap.png b/VEEPortingGuide/images/font-external-font-heap.png new file mode 100644 index 000000000..704023378 Binary files /dev/null and b/VEEPortingGuide/images/font-external-font-heap.png differ diff --git a/VEEPortingGuide/images/mock-framework-RT595_VirtualDevice_WearableDemo.png b/VEEPortingGuide/images/mock-framework-RT595_VirtualDevice_WearableDemo.png new file mode 100644 index 000000000..648d95c22 Binary files /dev/null and b/VEEPortingGuide/images/mock-framework-RT595_VirtualDevice_WearableDemo.png differ diff --git a/Tutorials/images/tuto_testsuite_fs_all_tests_passed.PNG b/VEEPortingGuide/images/tuto_testsuite_fs_all_tests_passed.PNG similarity index 100% rename from Tutorials/images/tuto_testsuite_fs_all_tests_passed.PNG rename to VEEPortingGuide/images/tuto_testsuite_fs_all_tests_passed.PNG diff --git a/Tutorials/images/tuto_testsuite_plug_uart_wrover.JPG b/VEEPortingGuide/images/tuto_testsuite_plug_uart_wrover.JPG similarity index 100% rename from Tutorials/images/tuto_testsuite_plug_uart_wrover.JPG rename to VEEPortingGuide/images/tuto_testsuite_plug_uart_wrover.JPG diff --git a/VEEPortingGuide/images/ui_display_copyswap_parallel.png b/VEEPortingGuide/images/ui_display_transmitswap_parallel.png similarity index 100% rename from VEEPortingGuide/images/ui_display_copyswap_parallel.png rename to VEEPortingGuide/images/ui_display_transmitswap_parallel.png diff --git a/VEEPortingGuide/images/ui_display_copyswap_serial.png b/VEEPortingGuide/images/ui_display_transmitswap_serial.png similarity index 100% rename from VEEPortingGuide/images/ui_display_copyswap_serial.png rename to VEEPortingGuide/images/ui_display_transmitswap_serial.png diff --git a/VEEPortingGuide/images/ui_display_tree_parallel.png b/VEEPortingGuide/images/ui_display_tree_parallel.png index 521da33b1..ce0f71ae7 100644 Binary files a/VEEPortingGuide/images/ui_display_tree_parallel.png and b/VEEPortingGuide/images/ui_display_tree_parallel.png differ diff --git a/VEEPortingGuide/images/ui_display_tree_serial.png b/VEEPortingGuide/images/ui_display_tree_serial.png index e624104cf..c7ae81155 100644 Binary files a/VEEPortingGuide/images/ui_display_tree_serial.png and b/VEEPortingGuide/images/ui_display_tree_serial.png differ diff --git a/VEEPortingGuide/images/ui_overview2.pptx b/VEEPortingGuide/images/ui_overview2.pptx index ea90b8818..36967b5a3 100644 Binary files a/VEEPortingGuide/images/ui_overview2.pptx and b/VEEPortingGuide/images/ui_overview2.pptx differ diff --git a/VEEPortingGuide/images/vee-port-creation.pptx b/VEEPortingGuide/images/vee-port-creation.pptx new file mode 100644 index 000000000..f89f6fd2d Binary files /dev/null and b/VEEPortingGuide/images/vee-port-creation.pptx differ diff --git a/VEEPortingGuide/images/veeport-creation-decision-tree.png b/VEEPortingGuide/images/veeport-creation-decision-tree.png new file mode 100644 index 000000000..c6f1cfcfb Binary files /dev/null and b/VEEPortingGuide/images/veeport-creation-decision-tree.png differ diff --git a/VEEPortingGuide/images/vgLL.pptx b/VEEPortingGuide/images/vgLL.pptx index a51d6ff5e..84cd345c5 100644 Binary files a/VEEPortingGuide/images/vgLL.pptx and b/VEEPortingGuide/images/vgLL.pptx differ diff --git a/VEEPortingGuide/images/vg_cco.png b/VEEPortingGuide/images/vg_cco.png index 05e938ce0..de77df455 100644 Binary files a/VEEPortingGuide/images/vg_cco.png and b/VEEPortingGuide/images/vg_cco.png differ diff --git a/VEEPortingGuide/images/vg_llapi_bvi.png b/VEEPortingGuide/images/vg_llapi_bvi.png index 088da76ad..944ab6d35 100644 Binary files a/VEEPortingGuide/images/vg_llapi_bvi.png and b/VEEPortingGuide/images/vg_llapi_bvi.png differ diff --git a/VEEPortingGuide/images/vg_llapi_emb.png b/VEEPortingGuide/images/vg_llapi_emb.png index 5e6f3e043..a89b56c2b 100644 Binary files a/VEEPortingGuide/images/vg_llapi_emb.png and b/VEEPortingGuide/images/vg_llapi_emb.png differ diff --git a/VEEPortingGuide/images/vg_llapi_font.png b/VEEPortingGuide/images/vg_llapi_font.png index 0d3018305..daf0dc4c5 100644 Binary files a/VEEPortingGuide/images/vg_llapi_font.png and b/VEEPortingGuide/images/vg_llapi_font.png differ diff --git a/VEEPortingGuide/images/vg_llapi_gradient.png b/VEEPortingGuide/images/vg_llapi_gradient.png index 5e95bef5b..31867cccd 100644 Binary files a/VEEPortingGuide/images/vg_llapi_gradient.png and b/VEEPortingGuide/images/vg_llapi_gradient.png differ diff --git a/VEEPortingGuide/images/vg_llapi_matrix.png b/VEEPortingGuide/images/vg_llapi_matrix.png index 4198715bb..de9b285f4 100644 Binary files a/VEEPortingGuide/images/vg_llapi_matrix.png and b/VEEPortingGuide/images/vg_llapi_matrix.png differ diff --git a/VEEPortingGuide/images/vg_llapi_path.png b/VEEPortingGuide/images/vg_llapi_path.png index 127025722..213e161de 100644 Binary files a/VEEPortingGuide/images/vg_llapi_path.png and b/VEEPortingGuide/images/vg_llapi_path.png differ diff --git a/VEEPortingGuide/index.rst b/VEEPortingGuide/index.rst index b92433da4..27358a113 100644 --- a/VEEPortingGuide/index.rst +++ b/VEEPortingGuide/index.rst @@ -3,47 +3,10 @@ VEE Porting Guide ================= -This document explains how the core features are -accessed, configured and used for creating a port of MICROEJ VEE (VEE Port) on your dedicated device. -It also explains how an Application can interoperate with native code, and -the details of the Architecture modules, including their APIs, error codes -and options. Semantics of implemented Foundation Libraries are described in -their respective chapters as well as the required Abstraction Layers APIs for porting them -to different targets. - -The following figure shows the overall process to obtain an Executable file to deploy on a device. -The first three steps are performed within MICROEJ SDK. The remaining steps are performed within the C IDE. - -.. _fig_overall-process: -.. figure:: images/process-overview5.* - :alt: Overall Build Process - :scale: 80% - :align: center - - Overall Build Process - -The steps are as follow: - -1. Create a new VEE Port configuration project. This project - describes the VEE Port to build (Architecture selection). - -2. Select which modules provided by the Architecture and Packs will be - installed in the VEE Port. - -3. Build the VEE Port according to the choices made in steps 1 and 2. - -4. Build an Application against the VEE Port in order - to obtain an object file to link in the BSP. - -5. Compile the BSP and link it with the Application object file that was - built previously in step 4 to produce an Executable. - -6. Final step: Deploy the Executable (i.e. the binary application) onto a device. - .. toctree:: - :hidden: - :maxdepth: 3 + :maxdepth: 1 + introduction architecture pack platformCreation diff --git a/VEEPortingGuide/introduction.rst b/VEEPortingGuide/introduction.rst new file mode 100644 index 000000000..f6e9f2dcc --- /dev/null +++ b/VEEPortingGuide/introduction.rst @@ -0,0 +1,187 @@ +============ +Introduction +============ + +A MicroEJ Architecture is a software package that includes the 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. MicroEJ Architectures are provided by MICROEJ SDK. + +A VEE Port is a MicroEJ Architecture port for a custom device. + +It relies on C drivers (a.k.a. low level LL drivers) for each VEE Port feature. +These drivers are implemented in the VEE Port BSP project. This project is edited in the C compiler IDE/dev environment (e.g. KEIL, GCC, IAR). +For example, the MicroUI library LED feature will require a ``LLUI_LED.c`` that implements the native on/off IO drive. + +Each VEE Port is specific to: + +* a MicroEJ Architecture (MCU ISA and C compiler) +* an optional RTOS (e.g. FreeRTOS - note: the MicroEJ Runtime can run bare metal) +* a device: the OS bring up code that is device-specific (e.g. the MCU specific code/IO/RAM/Clock/Middleware… configurations) + +MicroEJ Corp. provides MicroEJ Evaluation Architectures at https://repository.microej.com/modules/com/microej/architecture, +and `VEE Port Examples`_ for various evaluation boards. + +The VEE Porting Guide explains how the core features are +accessed, configured and used to create a port of MICROEJ VEE (VEE Port) on your dedicated device. +It also explains how an Application interacts with native code, and +the details of the Architecture modules, including their APIs, error codes +and options. + +Semantics of implemented Foundation Libraries are described in +their respective chapters as well as the required Abstraction Layers APIs for porting them +to different targets. + +.. _VEE Port Examples: https://github.com/microej?q=vee&type=all&language=&sort= + +VEE Port Build Process +====================== + +The following figure shows the overall process to create an Executable file to deploy on a device. +The first three steps are performed within MICROEJ SDK. The remaining steps are performed within the C IDE. + +.. _fig_overall-process: +.. figure:: images/process-overview5.* + :alt: Overall Build Process + :scale: 80% + :align: center + + Overall Build Process + +The steps are as follow: + +1. Create a new VEE Port configuration project. This project + describes the VEE Port to build (Architecture selection). + +2. Select which modules provided by the Architecture and Packs will be + installed in the VEE Port. + +3. Build the VEE Port according to the choices made in steps 1 and 2. + +4. Build an Application against the VEE Port in order + to obtain an object file to link in the BSP. + +5. Compile the BSP and link it with the Application object file that was + built previously in step 4 to produce an Executable. + +6. Final step: Deploy the Executable (i.e. the binary application) onto a device. + +Create a VEE Port for a Custom Device +===================================== + +VEE Port creation can either be done from scratch or modifying an existing VEE Port example project. +The following chart provides a handy guide to ease decision: + + .. figure:: images/veeport-creation-decision-tree.png + :alt: VEE Port Creation Decision Tree + :align: center + +Before going on, make sure that the new device hardware is validated and at least a trace output is available. +It is also a good idea to run basic hardware tests like: + +* Internal and external flash programming and verification +* RAM 8/16/32 -bit read/write operations (internal and external if any) +* EEMBC Coremark benchmark to verify the CPU/buses/memory/compiler configuration + +A VEE Port Example is already available for the same MCU/RTOS/C Compiler +------------------------------------------------------------------------ + +This is the fastest way: `VEE Port Examples`_ are usually provided for a silicon vendor evaluation board. +Import this VEE Port in MICROEJ SDK. + +As the MCU, RTOS and compiler are the same, only the device-specific code needs to be changed (external RAM, external oscillator, communication interfaces). + +VEE Port Configuration +:::::::::::::::::::::: + +* Modify the ``xxx-configuration`` project to match the device features and its associated configuration (e.g. GUI, Networking, ...). + +Refer to :ref:`VEE Port configuration ` to learn more about it. + +More details on available modules can be found in the :ref:`vee-porting-guide`. + +BSP +::: + +Required actions: + +* modify the BSP C project to match the device specification: + + * edit the scatter file/link options + * edit the compilation options + +* create/review/change the platform Low Level C drivers. + They must match the device components and the MCU IO pin assignment: + + .. note:: + + A number of ``LL*.h`` files are referenced from the project. + Implement the function prototypes declared there so that the Core Engine can delegate the relevant operations to the provided BSP C functions. + +Simulator +::::::::: + +In the SDK: + +* modify the existing Simulator Front Panel ``xxx-fp`` project + +A VEE Port Example is not available for the same MCU/RTOS/C Compiler +-------------------------------------------------------------------- + +Look for an available `VEE Port Example `_ that will match in order of priority: + +* same MCU part number. +* same RTOS. +* same C compiler. + +At this point, consider either to modify the closest VEE Port: + +* In the SDK: modify the VEE Port configuration. +* in the C IDE: start from an empty project that match with the MCU. + +Or to start from scratch a new VEE Port: + +* In the SDK: create the VEE Port and refer to the selected VEE Port as a model for implementation + (refer to the :ref:`VEE Port Creation ` documentation). +* in the C IDE: start from an empty project and implement the drivers of each of the LL drivers API. + + Make sure to link with: + + * the ``microejruntime.a`` that runs the Core Engine for a specific MCU Architecture + * the ``microejapp.o`` that contains the compiled Java application + +MCU +::: + +The MCU specific code can be found: + +* in the C project IDE properties +* in the linker file +* the IO configuration +* in the low level driver (these drivers are usually provided by the silicon vendor) + +RTOS +:::: + +The LL driver is named ``LLMJVM_[RTOS].c/.h``. Modify this file to match the selected RTOS. + +C Compiler +:::::::::: + +The BSP project is provided for a specific compiler (that matches the selected platform architecture). +Start a new project with the compiler IDE that includes the LL drivers and start the VEE Port in the ``main()`` function. + +Platform Validation +------------------- + +Refer to :ref:`veeport_qualification` to qualify the VEE Port. + +Further Assistance Needed +------------------------- + +Please note that porting MicroEJ to a new device is also something that is part of our engineering services. Consider contacting `our sales team `_ to request a quote. + +.. + | Copyright 2021-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/mock.rst b/VEEPortingGuide/mock.rst index 3b2b68ff8..e645e33ce 100644 --- a/VEEPortingGuide/mock.rst +++ b/VEEPortingGuide/mock.rst @@ -356,6 +356,225 @@ The Module serves two purposes, depending on whether it is added to a Mock or a - In a Mock project, JavaFX is added as a compile-time dependency, its content is not included in the Mock. - If your VEE Port contains at least one Mock, JavaFX must be added to the VEE Port project in order to embed its content in the VEE Port. +Mock Framework +============== + +The Mock Framework is a library based on JavaFX, it aims to ease the development of mock UIs. + +The Mock Framework provides a set of widgets. It allows to automatically generate the native method implementation +of an application and link it with the widgets of the mock UI. + +.. figure:: images/mock-framework-RT595_VirtualDevice_WearableDemo.png + :alt: Mock Framework used to mock Heart Rate sensor on Wearable Demo + :align: center + :scale: 75 % + + Mock Framework used to mock Heart Rate sensor on Wearable Demo. + +Usage +----- + +The following steps should be followed to create a mock using the Mock Framework: + +- Create Mock Framework Properties to bind the native methods to the mock UI, +- Create Widgets to manipulate the values of the above Properties, +- Create a Dashboard to hold the Widgets. + +Mock Framework Property +~~~~~~~~~~~~~~~~~~~~~~~ + +The Mock Framework uses a property system to bind widgets to the native methods. +A property holds a value and can trigger listeners when updated. + +A property must extend ``MockProperty`` and be annotated with ``@Property``: + +.. code-block:: java + + @Property + public class MyProperty extends MockProperty { + ... + } + +The annotation is used by the framework to find any property declared in the mock project. +The property can then be retrieved from its class: + +.. code-block:: java + + MyProperty property = MockupApplication.getProperty(MyProperty.class); + + +There are ready to use implementations of ``MockProperty``: + +- ``BooleanProperty`` +- ``IntegerProperty`` +- ``LongProperty`` +- ``FloatProperty`` +- ``DoubleProperty`` +- ``NumberProperty`` +- ``StringProperty`` +- ``FileProperty`` + +Getter and Setter Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Let's consider the following application code that defines getter and setter native methods: + +.. code-block:: java + + package com.microej.example; + + public class RandomService { + + private RandomService() { + } + + /** + * Gets the service state. + * + * @return true if the service is enabled, false otherwise. + */ + public static native boolean getEnable(); + + /** + * Sets the service state. + * + * @param enable + * enables or disables the service. + */ + public static native void setEnable(boolean enable); + + ... + +The native method implementation code can be generated using the following attributes in the Property annotation: + +- ``getter=""`` for the native method that retrieves a value from the mock. +- ``setter=""`` for the native method that sets a value in the mock. + +.. code-block:: java + + @Property(getter = "com.microej.example.RandomService.getEnable") + public class MyProperty extends BooleanProperty { + ... + } + +or + +.. code-block:: java + + @Property(getter = "com.microej.example.RandomService.getEnable", setter = "com.microej.example.RandomService.setEnable") + public class MyProperty extends BooleanProperty { + ... + } + +These attributes are optional. When no attribute is specified, the corresponding code will not be generated. + +The ```` is the fully qualified name of the method, +it must contain the package, the name of the class in which the native is implemented, and the native method name. +It must not contain parenthesis and arguments. + +Note that the class containing the ``getter`` and the ``setter`` can be different. + +Property values can be changed from the mock code with ``getValue()`` and ``setValue()`` methods: + +.. code-block:: java + + /* Get MyProperty value */ + boolean state = MockupApplication.getProperty(MyProperty.class).getValue(); + + /* Set MyProperty value */ + MockupApplication.getProperty(MyProperty.class).setValue(!state); + + +Mock Framework Widgets +~~~~~~~~~~~~~~~~~~~~~~ + +The Mock Framework provides some widgets to manipulate properties. + +Interacting with the widget modifies the underlying property, +and similarly, updating the property value modifies the state of the widget. + +- ``CheckBox``: sets the value of a ``BooleanProperty``. The property is set to ``true`` when the box is checked, and ``false`` otherwise. +- ``NumberSlider``: sets a value of a ``NumberProperty`` between the bounds defined by the property. The bounds and the position of the slider are automatically updated with the property. +- ``BoundsSetter``: displays the upper and lower bounds defined in the ``NumberProperty``. This class is abstract and needs to be used as a specialized subclass, such as ``IntegerBoundsSetter`` for integer values. +- ``Container``: widget that contains other Mock Framework Widgets. By default, it displays contained widgets vertically. +- ``Choice``: widget container providing a radio button list for each contained widget. Only the selected widget will be enabled and the other disabled (not clickable). +- ``FileChooser``: displays a button that opens a standard platform file dialog for selecting a file. Once the file is selected, the property is updated with the corresponding file object. +- ``TitledWidget``: decorator to add a title to a widget. +- ``ImageSwapWidget``: stores two images and shows one of them based on a boolean property. +- ``JavaFxWidget``: abstract class that can be extended to create custom widgets using JavaFX components. + + +Mock Framework Dashboard +~~~~~~~~~~~~~~~~~~~~~~~~ + +The Mock Framework Dashboard represents the window that is opened at Application startup on Simulator. It holds the Mock widgets. + +Mock widgets can be bound to Mock properties by passing the property class as an argument of the Mock widget. + +A Dashboard must extend ``AbstractDashboard`` and be annotated with ``@DashBoard`` annotation. + +.. code-block:: java + + @DashBoard(title = "My Mock DashBoard") + public class MockDashBoard extends AbstractDashboard { + + public MockDashBoard() { + addWidget(new CheckBox("Enable RandomService", MyProperty.class)); + } + } + +``@DashBoard`` attributes are optional, find below the list of available ones: + +- ``title``: sets the title of the mock window, default title is *VD Control Center*. +- ``icon``: sets the icon of the mock window, the path is relative to the ``src/main/resources`` folder of the mock project (e.g. ``icon="images/myIcon.png"``). +- ``width``: sets the width of the mock window. The default value is negative. When not specified, the system sets the mock window size automatically. +- ``height``: sets the height of the mock window. The default value is negative. When not specified, the system sets the mock window size automatically. + +Examples +-------- + +- `Mock Framework Examples `__ demonstrate the use of the Mock Framework. + +Installation +------------ + +.. tabs:: + + .. tab:: SDK 6 + + - Add the Mock Framework dependency to your Mock project: + + .. code-block:: kotlin + + implementation("com.microej.library.mock:mock-framework:1.0.1") + + - Add the JavaFX dependency to your Mock project which is required to compile the mock: + + .. code-block:: kotlin + + compileOnly(group="com.microej.tool", name="javafx", version="1.2.0", configuration="provided") + + - Add the Mock Framework and JavaFX annotation processors dependencies to your Mock project: + + .. code-block:: kotlin + + annotationProcessor("com.microej.library.mock:mock-framework:1.0.1") + annotationProcessor(group="com.microej.tool", name="javafx", version="1.2.0", configuration="provided") + + .. tab:: SDK 5 + + - Add the Mock Framework dependency to your Mock project: + + .. code-block:: xml + + + + - Add the JavaFX dependency to your Mock project which is required to compile the mock: + + .. code-block:: xml + + + .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/VEEPortingGuide/platformMigration.rst b/VEEPortingGuide/platformMigration.rst index c1bf9a857..6969dcf06 100644 --- a/VEEPortingGuide/platformMigration.rst +++ b/VEEPortingGuide/platformMigration.rst @@ -392,7 +392,7 @@ Going further Now that the Platform is connected to the BSP it can leverage the Java Test Suites provided by the `Platform Qualification Tools`_. -See :ref:`tutorial_run_test_suite_on_device` for a step by step +See :ref:`run_test_suite_on_device` documentation for a step by step explanation on how to do so. .. _Platform Qualification Tools: https://github.com/MicroEJ/VEEPortQualificationTools diff --git a/Tutorials/tutorialRunATestSuiteOnDevice.rst b/VEEPortingGuide/runFsTestSuiteOnESP32WROVER.rst similarity index 77% rename from Tutorials/tutorialRunATestSuiteOnDevice.rst rename to VEEPortingGuide/runFsTestSuiteOnESP32WROVER.rst index 11c5f464a..4fd415ec9 100644 --- a/Tutorials/tutorialRunATestSuiteOnDevice.rst +++ b/VEEPortingGuide/runFsTestSuiteOnESP32WROVER.rst @@ -1,53 +1,36 @@ -.. _tutorial_run_test_suite_on_device: +.. _run_fs_test_suite_on_esp32_wrover: -Run a Test Suite on a Device -============================ +Run the FS Test Suite on ESP32-WROVER VEE Port +============================================== -This tutorial describes all the steps to configure and run a -:ref:`vee_port_testsuite` on a device using the `Platform +This guide describes all the steps to configure and run a +:ref:`vee_port_testsuite` on a device using the `Port Qualification Tools `_. -In this tutorial, the target device is the Espressif ESP32-WROVER-KIT +The target device is the Espressif ESP32-WROVER-KIT V4.1 board and the Filesystem Test Suite for :ref:`FS ` module will be used as an example. -The tutorial should take 1 hour to complete (excluding the Platform -Getting Started setup). - -Intended Audience and Scope ---------------------------- - -The audience for this document is software engineers who want to -validate an Abstraction Layer implementation or understand how to automatically -run a MicroEJ Test Suite on their device. - -The following topics are out of the scope of this tutorial: - -- How to write test cases and package a Test Suite module. See - :ref:`application_testsuite` for this topic. -- How to create a new Foundation Library. See the `Foundation Library - Getting Started - `_ - to learn more about creating custom Foundation Library. +This guide should take 1 hour to complete (excluding the VEE Port +setup from the Getting Started page). Prerequisites ------------- -This tutorial assumes the following: +This guide assumes the following: - Good knowledge of the :ref:`chapter-glossary`. - Tutorial :ref:`tutorialUnderstandMicroEJFirmwareBuild` has been followed. -- MicroEJ SDK distribution 20.07 or more (see :ref:`get_sdk_version`). +- MICROEJ SDK distribution 20.07 or more (see :ref:`get_sdk_version`). -- The `WROVER Platform +- The `WROVER VEE Port `__ has been properly setup (i.e., it can be used to generate a Mono-Sandbox Executable). -The explanation can be adapted to run the test suite on any other -MicroEJ Platform providing: +The instructions of this page can be adapted to run the test suite on any other VEE Port providing: - An implementation of :ref:`LLFS-API-SECTION` version 1.0.2 in `com.microej.pack#fs-4.0.3`_. @@ -55,7 +38,7 @@ MicroEJ Platform providing: .. note:: - This tutorial can also be adapted to run other test suites in addition to the + This documentation can also be adapted to run other test suites in addition to the Filesystem Test Suite presented here. .. _com.microej.pack#fs-4.0.3: https://repository.microej.com/modules/com/microej/pack/fs/4.0.3/ @@ -63,7 +46,7 @@ MicroEJ Platform providing: Introduction ------------ -This tutorial presents a local setup of the :ref:`vee_port_testsuite` +This guide presents a local setup of the :ref:`vee_port_testsuite` for the :ref:`FS ` Foundation Library on a concrete device (not on Simulator). @@ -73,7 +56,7 @@ In essence, a Foundation Library provides an API to be used by an Application or :alt: MicroEJ Foundation Libraries and Add-On Libraries :align: center - MicroEJ Foundation Libraries, Add-On Libraries and MicroEJ Application + MicroEJ Foundation Libraries, Add-On Libraries and Application For example, the Java file system API `java.io.File`_ is provided by the MicroEJ Foundation Library named `FS`_. The Abstraction Layer of @@ -88,15 +71,15 @@ Import the Test Suite --------------------- Follow these steps to import the Filesystem Test Suite into the -workspace from the `Platform Qualification Tools +workspace from the `Port Qualification Tools `__: -- Clone or download the `Platform Qualitification Tools project 2.3.0 +- Clone or download the `Port Qualitification Tools project 2.3.0 `__. - Select :guilabel:`File` > :guilabel:`Import...`. - Select :guilabel:`Existing Projects into Workspace`. - Set :guilabel:`Select the root directory` to the directory - ``tests/fs`` in the Platform Qualification Tools fetched in the + ``tests/fs`` in the Port Qualification Tools fetched in the previous step. - Ensure :guilabel:`Copy projects into workspace` is checked. - Click on :guilabel:`Finish`. @@ -115,8 +98,8 @@ should be used to validate the Abstraction Layer implementation. Please refer to :ref:`test_suite_versioning` to determine the correct Test Suite version to use. -On the WROVER Platform, the FS Test Suite version to use is specified -in ``{PLATFORM}-configuration/testsuites/fs/README.md``. The Test +On the WROVER VEE Port, the FS Test Suite version to use is specified +in ``{VEE Port}-configuration/testsuites/fs/README.md``. The Test Suite version must be set in the ``module.ivy`` of the ``java-testsuite-fs`` project (e.g. ``java-testsuite-fs/module.ivy``). For example: @@ -125,13 +108,13 @@ For example: -Configure the Platform BSP Connection +Configure the VEE Port BSP Connection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Several properties must be defined depending on the type of BSP -Connection used by the MicroEJ Platform. +Connection used by the VEE Port. -For a MicroEJ Application, these properties are set using the launcher +For a Application, these properties are set using the launcher of the application. For a Test Suite, the properties are defined in a file named ``config.properties`` in the root folder of the Test Suite. For example, see this example of `config.properties @@ -151,11 +134,11 @@ trace to determine the result of the execution. To do that, we will use the :ref:`tool_serial_to_socket` tool to redirect the execution traces dumped to a COM port. -The WROVER platform used in this tutorial is particular because +The WROVER VEE Port used in this documentation is particular because the UART port is already used to flash the device. Thus, a separate UART port must be used for the trace output. -This platform defines the option +This VEE Port defines the option ``microej.testsuite.properties.debug.traces.uart`` to redirect traces from standard input to UART. @@ -163,7 +146,7 @@ from standard input to UART. :alt: Plug alternative UART on WROVER GND/D0 :align: center -See the `Testsuite Configuration section of the WROVER Platform documentation +See the `Testsuite Configuration section of the WROVER VEE Port documentation `__ for more details. @@ -187,7 +170,7 @@ Transmitter: - Set :guilabel:`Name` to ``Serial To Socket Transmitter``. - - Select a MicroEJ Platform available in the workspace in + - Select a VEE Port available in the workspace in :guilabel:`Target` > :guilabel:`Platform`. - Select ``Serial To Socket Transmitter`` in :guilabel:`Execution` > @@ -214,19 +197,19 @@ various properties may be required and adjusted. See the file https://github.com/MicroEJ/VEEPortQualificationTools/blob/2.3.0/tests/fs/java/java-testsuite-fs/validation/microej-testsuite-common.properties) and the README of the Test Suite for a description of each property. -On the WROVER Platform, the configuration files ``config.properties`` +On the WROVER VEE Port, the configuration files ``config.properties`` and ``microej-testsuite-common.properties`` are provided in -``{PLATFORM}-configuration/testsuites/fs/``. +``{VEE Port}-configuration/testsuites/fs/``. In ``config.properties``, the property ``target.platform.dir`` must be -set to the absolute path to the platform. For example +set to the absolute path to the VEE Port. For example ``C:/P0065_ESP32-WROVER-Platform/ESP32-WROVER-Xtensa-FreeRTOS-platform/source``. Run the Test Suite ---------------------- -To run the Test Suite, right click on the Test Suite module and select +To run the Test Suite, right-click on the Test Suite module and select ``Build Module``. Configure the Tests to Run @@ -256,7 +239,7 @@ Several reasons might explain why to exclude some tests: - **Known bugs in the Foundation Library**. The latest version of the Test Suite for a given Foundation Library might contain regression - tests or tests for new features. If the MicroEJ Platform doesn't + tests or tests for new features. If the VEE Port doesn't use the latest Foundation Library, then it can be necessary to exclude the new tests. diff --git a/VEEPortingGuide/uiBRS.rst b/VEEPortingGuide/uiBRS.rst index 36d431d2c..ba45f3377 100644 --- a/VEEPortingGuide/uiBRS.rst +++ b/VEEPortingGuide/uiBRS.rst @@ -111,7 +111,7 @@ This illustration symbolizes the basic principle of the Graphics Engine's timeli * *drawing(s)* symbolizes one or several drawings in the back buffer. * *flush* symbolizes the call to the LLAPI ``LLUI_DISPLAY_IMPL_flush()`` that allows the display driver to update the display panel content according to the :ref:`display connection` (serial or parallel). -* *post-flush* symbolizes the moment between the end of flush (end of swap, end of transmission, or end of copy) and the unlocking of the Graphics Engine (the call to ``LLUI_DISPLAY_setDrawingBuffer()``). Before this call, the Graphics Engine is not allowed to draw in the buffer. +* *post-flush* symbolizes the moment between the end of flush (end of swap, end of transmission, or end of copy) and the unlocking of the Graphics Engine (the call to ``LLUI_DISPLAY_setBackBuffer()``). Before this call, the Graphics Engine is not allowed to draw in the buffer. .. note:: The time between the *post-flush* and *drawing(s)* depends on the application: the first drawing after a *flush* can occur immediately after the *post-flush* or later. @@ -224,7 +224,7 @@ The BRS is responsible for implementing the LLAPI (the hooks, see above) and man When the application calls ``Display.flush()``, the Graphics Engine immediately calls the LLAPI ``LLUI_DISPLAY_IMPL_refresh()``. This call allows the BRS: - * to finalize (if required) the back buffer (no drawing will be performed into the buffer until the next call to ``LLUI_DISPLAY_setDrawingBuffer()``), + * to finalize (if required) the back buffer (no drawing will be performed into the buffer until the next call to ``LLUI_DISPLAY_setBackBuffer()``), * **and** to call the LCD driver flush function ``LLUI_DISPLAY_IMPL_flush()`` by giving the region(s) to update on the display panel. Strategies @@ -276,8 +276,6 @@ In this case, the restoration is useless because the back buffer always contains Single Buffer (parallel) -.. note:: This chapter uses the display connection *serial* to describe the flow, but it is similar to the display connection *parallel* (*copy* instead of *transmit*). - The principle of this strategy is to cumulate the drawing regions. The refresh consists in transmitting these regions (a list of rectangles) that have been modified since the last flush (or a unique rectangle that encapsulates all the regions) to the LCD driver through the LLAPI ``LLUI_DISPLAY_IMPL_flush()``. @@ -354,7 +352,7 @@ Here are the steps around the strategy describing how to use it: 2. A ``Display.flush()`` is asked, the Graphics Engine calls ``LLUI_DISPLAY_IMPL_refresh()``. 3. The strategy calls ``LLUI_DISPLAY_IMPL_flush()``. 4. The display driver has to implement ``LLUI_DISPLAY_IMPL_flush()``, which consists in transmitting the back buffer data to the front buffer. -5. As soon as the transmission is performed, the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the same back buffer address (there is only one buffer). +5. As soon as the transmission is performed, the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the same back buffer address (there is only one buffer). 6. The Graphics Engine is now unlocked, and a new drawing can start in the back buffer. .. _section_brs_predraw: @@ -469,7 +467,7 @@ The two buffers have the same role alternatively, back buffer and front buffer: 2. A ``Display.flush()`` is asked, the Graphics Engine calls ``LLUI_DISPLAY_IMPL_refresh()``. 3. The strategy calls ``LLUI_DISPLAY_IMPL_flush()``. 4. The display driver has to implement ``LLUI_DISPLAY_IMPL_flush()`` that consists in swapping the back and front buffers. -5. As soon as the display *uses* the new front buffer (the new back buffer is now freed), the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the new back buffer address (== previous front buffer). +5. As soon as the display *uses* the new front buffer (the new back buffer is now freed), the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the new back buffer address (== previous front buffer). 6. The Graphics Engine is now unlocked. 7. Before the very first drawing, this strategy copies the regions to restore from the previous back buffer to the new back buffer. 8. A new drawing can start in the new back buffer. @@ -502,7 +500,7 @@ On startup, the front buffer is mapped on buffer (C), buffer (A) is the back buf * buffer (B): new the application's back buffer * buffer (C): current LCD driver's buffer -5. The buffer (B) is immediately available (free): the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the buffer (B)'s address. +5. The buffer (B) is immediately available (free): the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the buffer (B)'s address. 6. The Graphics Engine is now unlocked. 7. Before the very first drawing, this strategy copies the regions to restore from the previous back buffer (A) to the new back buffer (B). 8. Some drawings are performed in the back buffer (B). @@ -517,32 +515,30 @@ On startup, the front buffer is mapped on buffer (C), buffer (A) is the back buf 13. The buffer (C) will now be used for the next drawings. Go to step 5. -Use (Copy and Swap Buffer) --------------------------- +Use (Transmit and Swap Buffer) +------------------------------ -Here are the steps around the strategy describing how to use it in :ref:`copy and swap` buffer policy. +Here are the steps around the strategy describing how to use it in :ref:`transmit and swap` buffer policy. .. tabs:: .. tab:: Serial Connection - .. figure:: images/ui_display_copyswap_serial.* - :alt: Copy and Swap (serial) + .. figure:: images/ui_display_transmitswap_serial.* + :alt: Transmit and Swap (serial) :scale: 50% :align: center - Copy and Swap (serial) + Transmit and Swap (serial) .. tab:: Parallel Connection - .. figure:: images/ui_display_copyswap_parallel.* - :alt: Copy and Swap (parallel) + .. figure:: images/ui_display_transmitswap_parallel.* + :alt: Transmit and Swap (parallel) :scale: 50% :align: center - Copy and Swap (parallel) - -.. note:: This chapter uses the display connection *serial* to describe the flow, but it is similar to the display connection *parallel* (*copy* instead of *transmit*). + Transmit and Swap (parallel) The two buffers have the same role alternatively: back buffer and transmission buffer. On startup, the transmission buffer has yet to be used. @@ -554,19 +550,19 @@ This subtlety allows the reuse of the same back buffer after the end of the tran 2. A ``Display.flush()`` is asked, the Graphics Engine calls ``LLUI_DISPLAY_IMPL_refresh()``. 3. The strategy calls ``LLUI_DISPLAY_IMPL_flush()``. 4. The display driver has to implement ``LLUI_DISPLAY_IMPL_flush()`` which consists in starting the transmission of the back buffer content to the LCD device's buffer and swapping both buffers (back and transmission buffers). -5. The new back buffer is immediately available (free); the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the new back buffer address (== previous transmission buffer). +5. The new back buffer is immediately available (free); the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the new back buffer address (== previous transmission buffer). 6. The Graphics Engine is now unlocked. 7. Before the very first drawing, this strategy copies the regions to restore from the previous back buffer to the new back buffer. 8. Some drawings are performed in the back buffer. 9. A second ``Display.flush()`` is asked, the Graphics Engine calls ``LLUI_DISPLAY_IMPL_refresh()``. 10. The strategy calls ``LLUI_DISPLAY_IMPL_flush()``. 11. The system is locked: the LCD driver still needs to finish transmitting the transmission buffer data to the LCD device's buffer. -12. As soon as the transmission is done, the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the new back buffer address (== previous transmission buffer). +12. As soon as the transmission is done, the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the new back buffer address (== previous transmission buffer). 13. The application is sleeping (doesn't want to draw in the back buffer) - .. hint:: Optimization: As soon as the transmission to the LCD device's buffer is done, the BSP should call again ``LLUI_DISPLAY_setDrawingBuffer()`` by giving the transmission buffer (which is now free). If the drawing has yet to start in the back buffer, the Graphics Engine will reuse this transmission buffer as a new back buffer instead of using the other one; the restoration becomes useless. + .. hint:: Optimization: As soon as the transmission to the LCD device's buffer is done, the BSP should call again ``LLUI_DISPLAY_setBackBuffer()`` by giving the transmission buffer (which is now free). If the drawing has yet to start in the back buffer, the Graphics Engine will reuse this transmission buffer as a new back buffer instead of using the other one; the restoration becomes useless. -14. The BSP should notify the Graphics Engine again by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the transmission buffer address: the Graphics Engine will reuse this buffer for future drawings, and the strategy will not need to restore anything. +14. The BSP should notify the Graphics Engine again by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the transmission buffer address: the Graphics Engine will reuse this buffer for future drawings, and the strategy will not need to restore anything. .. _section_brs_default: @@ -633,7 +629,7 @@ Here are the steps around the strategy describing how to use it: 2. A ``Display.flush()`` is asked, the Graphics Engine calls ``LLUI_DISPLAY_IMPL_refresh()``. 3. The strategy calls ``LLUI_DISPLAY_IMPL_flush()``. 4. The display driver has to implement ``LLUI_DISPLAY_IMPL_flush()``: at least enable the LCD refresh interrupt to wait until the end of the refresh (or use a software task). -5. In the LCD refresh interrupt (here, the display panel shows the latest frame for sure), the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the same buffer address. +5. In the LCD refresh interrupt (here, the display panel shows the latest frame for sure), the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the same buffer address. 6. The Graphics Engine is now unlocked. 7. Some drawings are performed in the back buffer. @@ -697,7 +693,7 @@ Here are the steps around the strategy describing how to use it: 2. A ``Display.flush()`` is asked, the Graphics Engine calls ``LLUI_DISPLAY_IMPL_refresh()``. 3. The strategy has to implement ``LLUI_DISPLAY_IMPL_refresh()`` and call ``LLUI_DISPLAY_IMPL_flush()``. 4. The display driver has to implement ``LLUI_DISPLAY_IMPL_flush()``. -5. When the display panel shows the latest frame, the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the buffer address. +5. When the display panel shows the latest frame, the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the buffer address. 6. The Graphics Engine is now unlocked. 7. Some drawings are performed in the buffer. @@ -788,7 +784,7 @@ Here are the steps around the strategy describing how to use it: 3. The strategy calls ``LLUI_DISPLAY_IMPL_flush()``. 4. The display driver has to implement ``LLUI_DISPLAY_IMPL_flush()``: swap the back buffer and the front buffer. 5. As soon as the display *uses* the new front buffer (the new back buffer is now freed), the BSP has to launch a copy of the new front buffer to the new back buffer (use the bounding box). -6. As soon as the copy is done (the copy may be asynchronous), the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the new back buffer address. +6. As soon as the copy is done (the copy may be asynchronous), the BSP has to notify the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the new back buffer address. 7. The Graphics Engine is now unlocked. 8. Some drawings are performed in the back buffer. @@ -821,7 +817,7 @@ The options (some *defines*) are shared between the strategies: * ``UI_DISPLAY_BRS_FLUSH_SINGLE_RECTANGLE`` (``ui_display_brs_configuration.h``): configures the number of rectangles that the strategy gives to the implementation of ``LLUI_DISPLAY_IMPL_flush()``. If not set, the number of regions depends on the strategy. If set, only one region is given: the bounding box of all drawing regions. Used by: - * Predraw: The list of regions is often useless (the LCD driver just has to swap the back and front buffers); however, this list can be used for the buffer policy :ref:`section_display_copyswap`. Calculating the bounding box uses takes a bit of memory and time; if the bounding box is not used, it is recommended to refrain from enabling this option. + * Predraw: The list of regions is often useless (the LCD driver just has to swap the back and front buffers); however, this list can be used for the buffer policy :ref:`section_display_transmitswap`. Calculating the bounding box uses takes a bit of memory and time; if the bounding box is not used, it is recommended to refrain from enabling this option. * Single: The list of regions can be useful to refresh small parts of the front buffer. * Legacy: This option is never used, and the bounding box of all drawing regions is given to the implementation of ``LLUI_DISPLAY_IMPL_flush()``. @@ -888,7 +884,7 @@ The available buffer policies are: - :ref:`Swap Triple Buffer `: ``ej.fp.widget.display.buffer.SwapTripleBufferPolicy``. - :ref:`Direct Buffer `: ``ej.fp.widget.display.buffer.DirectBufferPolicy``. - :ref:`section_display_single`: ``ej.fp.widget.display.buffer.SingleBufferPolicy``. -- :ref:`section_display_copyswap`: ``ej.fp.widget.display.buffer.CopySwapBufferPolicy``. +- :ref:`section_display_transmitswap`: ``ej.fp.widget.display.buffer.TransmitSwapBufferPolicy``. The available refresh strategies are: diff --git a/VEEPortingGuide/uiCco.rst b/VEEPortingGuide/uiCco.rst index 06f578010..519a14b89 100644 --- a/VEEPortingGuide/uiCco.rst +++ b/VEEPortingGuide/uiCco.rst @@ -181,7 +181,7 @@ This C module is a specific implementation of the C module MicroUI over STM32 DM * It is compatible with the :ref:`multiple destination formats ` module (but can only handle one destination format). * It is compatible with the :ref:`Buffer Refresh Strategies (BRS)` ``predraw``, ``single`` and ``legacy`` (switch). -This C module is available on the :ref:`central_repository`: `com.microej.clibrary.llimpl#display-dma2d`_. +This C module is available on the :ref:`developer_repository`: `com.microej.clibrary.llimpl#microui-dma2d`_. Files ----- @@ -225,7 +225,7 @@ This cache must be cleared before using the DMA2D: Usage """"" -1. Check the configuration of the define ``DRAWING_DMA2D_CACHE_MANAGEMENT`` in ``ui_drawing_dma2d_configuration.h``. +1. Check the configuration of the define ``DRAWING_DMA2D_CACHE_MANAGEMENT`` in ``ui_dma2d_configuration.h``. Buffer Refresh Strategy "Predraw" --------------------------------- @@ -262,7 +262,7 @@ Example of Implementation // notify the MicroUI Graphics Engine uint8_t* buffer = (uint8_t*)(BACK_BUFFER == LTDC_Layer->CFBAR ? FRAME_BUFFER : BACK_BUFFER); - LLUI_DISPLAY_setDrawingBuffer(g_current_flush_identifier, buffer, from_isr); + LLUI_DISPLAY_setBackBuffer(g_current_flush_identifier, buffer, from_isr); } void DMA2D_IRQHandler(void) { @@ -316,7 +316,7 @@ Example of Implementation void UI_DRAWING_DMA2D_memcpy_callback(bool from_isr) { // notify the MicroUI Graphics Engine - LLUI_DISPLAY_setDrawingBuffer(g_current_flush_identifier, (uint8_t*)BACK_BUFFER, from_isr); + LLUI_DISPLAY_setBackBuffer(g_current_flush_identifier, (uint8_t*)BACK_BUFFER, from_isr); } Buffer Refresh Strategy "Legacy" @@ -369,10 +369,10 @@ Example of Implementation void UI_DRAWING_DMA2D_memcpy_callback(bool from_isr) { // notify the MicroUI Graphics Engine uint8_t* buffer = (uint8_t*)(BACK_BUFFER == LTDC_Layer->CFBAR ? FRAME_BUFFER : BACK_BUFFER); - LLUI_DISPLAY_setDrawingBuffer(g_current_flush_identifier, buffer, from_isr); + LLUI_DISPLAY_setBackBuffer(g_current_flush_identifier, buffer, from_isr); } -.. _com.microej.clibrary.llimpl#display-dma2d: https://repository.microej.com/modules/com/microej/clibrary/llimpl/display-dma2d/ +.. _com.microej.clibrary.llimpl#microui-dma2d: https://forge.microej.com/ui/native/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-dma2d/ .. _section_ui_c_module_microui_vglite: @@ -395,26 +395,27 @@ Files ----- * Implements some functions of ``ui_drawing.h`` (see above). -* C files: ``ui_drawing_vglite_path.c``, ``ui_drawing_vglite_process.c``, ``ui_drawing_vglite.c`` and ``ui_vglite.c``. +* C files: ``mej_math.c``, ``ui_drawing_vglite_path.c``, ``ui_drawing_vglite_process.c``, ``ui_drawing_vglite.c`` and ``ui_vglite.c``. * Status: optional. Usage ----- 1. Add the C files to the BSP project. -2. Call ``UI_VGLITE_init()`` from ``LLUI_DISPLAY_IMPL_initialize()``. -3. Configure the options in ``ui_vglite_configuration.h``. -4. Comment the line ``#error [...]"``. -5. Call ``UI_VGLITE_IRQHandler()`` during the GPU interrupt routine. -6. Set the VGLite library's preprocessor define ``VG_DRIVER_SINGLE_THREAD``. -7. The VGLite library must be patched to be compatible with this C module: +2. Call ``UI_VGLITE_initialize`` from ``LLUI_DISPLAY_IMPL_initialize`` before calling any VGLite-related function. +3. Call ``UI_VGLITE_start`` from ``LLUI_DISPLAY_IMPL_initialize`` after configuring the VGLite library. +4. Configure the options in ``ui_vglite_configuration.h``. +5. Comment the line ``#error [...]"``. +6. Call ``UI_VGLITE_IRQHandler`` during the GPU interrupt routine. +7. Set the VGLite library's preprocessor define ``VG_DRIVER_SINGLE_THREAD``. +8. The VGLite library must be patched to be compatible with this C module: .. code-block:: bash cd [...]/sdk/middleware/vglite patch -p1 < [...]/3.0.15_rev7.patch -8. In the file ``vglite_window.c``, add the function ``VGLITE_CancelSwapBuffers()`` and its prototype in ``vglite_window.h``: +9. In the file ``vglite_window.c``, add the function ``VGLITE_CancelSwapBuffers()`` and its prototype in ``vglite_window.h``: .. code-block:: c @@ -535,81 +536,78 @@ Files ----- * Implements some functions of ``ui_drawing.h`` (see above). -* C file: ``ui_drawing_nema.c``. +* C files: ``ui_nema.c`` and ``ui_drawing_nema.c``. * Status: optional. Usage ----- -1. Add the C file to the BSP project. -2. Call ``UI_DRAWING_NEMA_initialize()`` from ``LLUI_DISPLAY_IMPL_initialize()``. -3. Configure the options in ``ui_drawing_nema_configuration.h``. -4. Comment the line ``#error [...]"``. -5. Choose between *interrupt mode* and *task mode* (see Implementation). +1. Add the C files to the BSP project. +2. Add ``ui_nemagfx/inc`` to the include path. +3. Call ``UI_NEMA_initialize()`` from ``LLUI_DISPLAY_IMPL_initialize()``. +4. Configure the options in ``ui_nema_configuration.h``. +5. Comment the line ``#error [...]"``. + +.. _section_ui_c_module_microui_nemagfx_implementation: Implementation -------------- The MicroUI Graphics Engine waits for the end of the asynchronous drawings (performed by the GPU). -The VEE Port must unlock this waiting by using one of these two solutions: - -* `Interrupt` mode: the GPU interrupt routine has to call the function ``UI_DRAWING_NEMA_post_operation()`` (the GPU interrupt routine is often written in the same file as the implementation of ``nema_sys_init()``). -* `Task` mode: the VEE Port has to add a dedicated task that will wait until the end of the drawings. +The VEE Port must stop this wait with a call to the function ``UI_NEMA_post_operation()`` in the GPU interrupt routine. -The `interrupt` mode is enabled by default. -To use the `task` mode, comment the define ``NEMA_INTERRUPT_MODE`` in ``ui_drawing_nema_configuration.h`` +.. tip:: -.. note:: You will find more details in the ``#define NEMA_INTERRUPT_MODE`` documentation. + The GPU interrupt routine is often written in the same file as the implementation of ``nema_sys_init()``. Options ------- This C module provides some drawing algorithms that are disabled by default. -* The rendering time of a simple shape with the GPU (time in the NemaGFX library + GPU setup time + rendering time) is longer than with software rendering. To enable the hardware rendering for simple shapes, uncomment the definition of ``ENABLE_SIMPLE_LINES`` in ``ui_drawing_nema_configuration.h``. -* The rendering of thick faded lines with the GPU is disabled by default: the quality of the rendering is too random. To enable it, uncomment the definition of ``ENABLE_FADED_LINES`` in ``ui_drawing_nema_configuration.h``. -* To draw a shape, the GPU uses the commands list. For rectangular shapes (draw/fill rectangles and images), the maximum list size is fixed (around 300 bytes). For the other shapes (circle, etc.), the list increases according to the shape size (dynamic shape): several blocks of 1024 bytes and 40 bytes are allocated and never freed. By default, the dynamic shapes are disabled, and the software algorithms are used instead. To enable the hardware rendering for dynamic shapes, uncomment the definition of ``ENABLE_DYNAMIC_SHAPES`` in ``ui_drawing_nema_configuration.h``. -* Some GPUs might not be able to render the images in specific memories. Comment the define ``ENABLE_IMAGE_ROTATION`` in ``ui_drawing_nema_configuration.h`` to not use the GPU to render the rotated images. +* The rendering time of a simple shape with the GPU (time in the NemaGFX library + GPU setup time + rendering time) is longer than with software rendering. To enable the hardware rendering for simple shapes, uncomment the definition of ``ENABLE_SIMPLE_LINES`` in ``ui_nema_configuration.h``. +* The rendering of thick faded lines with the GPU is disabled by default: the quality of the rendering is too random. To enable it, uncomment the definition of ``ENABLE_FADED_LINES`` in ``ui_nema_configuration.h``. +* Some GPUs might not be able to render the images in specific memories. Comment the define ``ENABLE_IMAGE_ROTATION`` in ``ui_nema_configuration.h`` to not use the GPU to render the rotated images. Drawings -------- The following table describes the accelerated drawings: -+-------------------------+-----------------------------------------------------------------------------+ -| Feature | Comment | -+=========================+=============================================================================+ -| Draw line | | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw horizontal line | Disabled by default (see above: ENABLE_SIMPLE_LINES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw vertical line | Disabled by default (see above: ENABLE_SIMPLE_LINES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw rectangle | Disabled by default (see above: ENABLE_SIMPLE_LINES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Fill rectangle | | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw rounded rectangle | Disabled by default (see above: ENABLE_DYNAMIC_SHAPES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Fill rounded rectangle | Disabled by default (see above: ENABLE_DYNAMIC_SHAPES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw circle | Disabled by default (see above: ENABLE_DYNAMIC_SHAPES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Fill circle | Disabled by default (see above: ENABLE_DYNAMIC_SHAPES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw image | ARGB8888, RGB565, A8 | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw thick faded line | Only with fade <= 1 | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw thick faded circle | Only with fade <= 1, disabled by default (see above: ENABLE_DYNAMIC_SHAPES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw thick line | Disabled by default (see above: ENABLE_FADED_LINES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw thick circle | Disabled by default (see above: ENABLE_DYNAMIC_SHAPES) | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw rotated image | See draw image | -+-------------------------+-----------------------------------------------------------------------------+ -| Draw scaled image | See draw image | -+-------------------------+-----------------------------------------------------------------------------+ ++-------------------------+------------------------------------------------------+ +| Feature | Comment | ++=========================+======================================================+ +| Draw line | | ++-------------------------+------------------------------------------------------+ +| Draw horizontal line | Disabled by default (see above: ENABLE_SIMPLE_LINES) | ++-------------------------+------------------------------------------------------+ +| Draw vertical line | Disabled by default (see above: ENABLE_SIMPLE_LINES) | ++-------------------------+------------------------------------------------------+ +| Draw rectangle | Disabled by default (see above: ENABLE_SIMPLE_LINES) | ++-------------------------+------------------------------------------------------+ +| Fill rectangle | | ++-------------------------+------------------------------------------------------+ +| Draw rounded rectangle | | ++-------------------------+------------------------------------------------------+ +| Fill rounded rectangle | | ++-------------------------+------------------------------------------------------+ +| Draw circle | | ++-------------------------+------------------------------------------------------+ +| Fill circle | | ++-------------------------+------------------------------------------------------+ +| Draw image | ARGB8888, RGB565, A8 | ++-------------------------+------------------------------------------------------+ +| Draw thick faded line | Only with fade <= 1 | ++-------------------------+------------------------------------------------------+ +| Draw thick faded circle | Only with fade <= 1 | ++-------------------------+------------------------------------------------------+ +| Draw thick line | Disabled by default (see above: ENABLE_FADED_LINES) | ++-------------------------+------------------------------------------------------+ +| Draw thick circle | | ++-------------------------+------------------------------------------------------+ +| Draw rotated image | See draw image | ++-------------------------+------------------------------------------------------+ +| Draw scaled image | See draw image | ++-------------------------+------------------------------------------------------+ Compatibility ============= diff --git a/VEEPortingGuide/uiChangeLog.rst b/VEEPortingGuide/uiChangeLog.rst index 8effd0fa9..1f55a186d 100644 --- a/VEEPortingGuide/uiChangeLog.rst +++ b/VEEPortingGuide/uiChangeLog.rst @@ -6,6 +6,96 @@ Changelog ========= +14.0.2 (2024-07-26) +=================== + +MicroUI +""""""" + +**Fixed** + +* Fix the rendering of anti-aliased arcs for some compilers (rounding issue). +* Fix a synchronization issue that may cause invalid parameters to be sent in the flush request. + +Front Panel +""""""""""" + +**Fixed** + +* Fix the infinite waiting on a display event when killing a feature. + +14.0.1 (2024-04-09) +=================== + +MicroUI +""""""" + +* Implement `MicroUI API 3.5.0`_. + +**Fixed** + +* Fix the infinite waiting on a display event when killing a feature. +* Fix the dump of the events queue when it is full. + +Front Panel +""""""""""" + +**Added** + +* Add ``LLUIDisplayImpl.getCurrentBackBuffer()`` (replace ``LLUIDisplayImpl.getCurrentDrawingBuffer()``). + +**Changed** + +* Homogenize the notions of back and front buffers. +* Set ``LLUIDisplayImpl.getCurrentDrawingBuffer()`` as deprecated: implement ``LLUIDisplayImpl.getCurrentBackBuffer()`` instead. + +LLAPIs +"""""" + +**Changed** + +* Homogenize the notions of back and front buffers: ``LLUI_DISPLAY_setBackBuffer()`` replaces ``LLUI_DISPLAY_setDrawingBuffer()``. + +C Module MicroUI +"""""""""""""""" + +* New version: `C Module MicroUI 4.0.1`_. + +**Changed** + +* Homogenize the notions of back and front buffers. + +**Fixed** + +* Disable the clip before calling ``UI_DISPLAY_BRS_restore()``. + +C Module DMA2D +"""""""""""""" + +* New version: `C Module DMA2D 5.0.1`_. + +**Changed** + +* Homogenize the notions of back and front buffers. + +C Module VGLite +""""""""""""""" + +* New version: `C Module VGLite 8.0.1`_. + +**Changed** + +* Homogenize the notions of back and front buffers. + +C Module NemaGFX +"""""""""""""""" + +* New version: `C Module NemaGFX 2.0.1`_. + +**Changed** + +* Homogenize the notions of back and front buffers. + 14.0.0 (2024-02-14) =================== diff --git a/VEEPortingGuide/uiDisplay.rst b/VEEPortingGuide/uiDisplay.rst index 4556a0545..9c5358269 100644 --- a/VEEPortingGuide/uiDisplay.rst +++ b/VEEPortingGuide/uiDisplay.rst @@ -177,7 +177,7 @@ The following table redirects to the right chapter according to the display buff - :ref:`Single ` * - Serial - 2 - - :ref:`Copy and Swap ` + - :ref:`Transmit and Swap ` * - Parallel - 1 - :ref:`Direct ` @@ -189,7 +189,7 @@ The following table redirects to the right chapter according to the display buff - :ref:`Swap Double ` or :ref:`Single ` * - Parallel - 3 - - :ref:`Swap Triple ` or :ref:`Copy and Swap ` + - :ref:`Swap Triple ` or :ref:`Transmit and Swap ` .. _section_display_direct: @@ -317,10 +317,10 @@ However, there are some differences: * In the *Swap Double* policy, the synchronization with the LCD controller is more effortless. An interrupt is thrown as soon as the LCD controller has updated its front buffer address. In the *Single* policy, the copy buffer process should be synchronized with the LCD tearing signal. * In the *Single* policy, during the copy, the destination buffer (the front buffer) is used by the copy buffer process (DMA, memcopy, etc.) and by the LCD controller. Both masters are using the same RAM section. This same RAM section switches in *Write* mode (copy buffer process) and *Read* mode (LCD controller). -.. _section_display_copyswap: +.. _section_display_transmitswap: -Copy and Swap Buffer --------------------- +Transmit and Swap Buffer +------------------------ Serial Connection """"""""""""""""" @@ -328,7 +328,7 @@ Serial Connection When the time to transmit the data from the back buffer to the front buffer is :ref:`too long `, a second buffer can be allocated in the MCU memory. The application can use this buffer while the first buffer is transmitted. This allows to anticipate the drawings even if the first drawings are not fully transmitted. -This is the notion of **copy and swap buffer**. +This is the notion of **transmit and swap buffer**. The buffers are usually called **back buffer 1** and **back buffer 2** (the display module's buffer is the **front buffer**). The *flush* step consists in transmitting the back buffer data to the display module memory **and** swapping both back buffers: @@ -337,12 +337,12 @@ The *flush* step consists in transmitting the back buffer data to the display mo * The back buffer 2 is not used: the application can immediately draw into it without waiting for the back buffer 1 to be transmitted. * At the end of the drawings in the back buffer 2, the back buffer 2 takes the role of the *transmission* buffer, and the back buffer 1 is free. -.. figure:: images/ui_display_copyswap_serial.* - :alt: Copy and Swap (serial) +.. figure:: images/ui_display_transmitswap_serial.* + :alt: Transmit and Swap (serial) :scale: 50% :align: center - Copy and Swap (serial) + Transmit and Swap (serial) Parallel Connection """"""""""""""""""" @@ -350,7 +350,7 @@ Parallel Connection When the time to copy the data from the back buffer to the front buffer is :ref:`too long `, a third buffer can be allocated in the MCU memory. This buffer can be used by the application during the copy of the first buffer. This allows to anticipate the drawings even if the first drawings still need to be entirely copied. -This is the notion of **copy and swap buffer**. +This is the notion of **transmit and swap buffer**. The buffers are usually called **back buffer 1** and **back buffer 2** (the third buffer is the **front buffer**). The *flush* step consists in copying the back buffer data to the front buffer **and** swapping both back buffers. @@ -358,12 +358,12 @@ The *flush* step consists in copying the back buffer data to the front buffer ** * The back buffer 2 is not used: the application can immediately draw into it without waiting for the back buffer 1 to be copied. * At the end of the drawings in the back buffer 2, the back buffer 2 takes the role of the *copying* buffer, and the back buffer 1 is free. -.. figure:: images/ui_display_copyswap_parallel.* - :alt: Copy and Swap (parallel) +.. figure:: images/ui_display_transmitswap_parallel.* + :alt: Transmit and Swap (parallel) :scale: 50% :align: center - Copy and Swap (parallel) + Transmit and Swap (parallel) .. _section_display_partial: @@ -971,7 +971,7 @@ The rendering frequency is cadenced on drawing time + flush time. .. figure:: images/uiDisplaySync05.* :width: 100% -As mentioned above, the idea is to use :ref:`two back buffers`. +As mentioned above, the idea is to use :ref:`two back buffers`. First, the UI task is drawing in the back buffer ``A``. Just after the call to `Display.flush()`_, the flush can start. During the flush time (copy of the back buffer ``A`` to the front buffer), the back buffer ``B`` can be used by the UI task to continue the drawings. @@ -1178,7 +1178,7 @@ This particular case is the easiest to write because the ``flush()`` stays empty void LLUI_DISPLAY_IMPL_flush(MICROUI_GraphicsContext* gc, uint8_t flush_identifier, const ui_rect_t areas[], size_t length) { // nothing to flush to the LCD, just have to unlock the Graphics Engine by giving the same buffer address - LLUI_DISPLAY_setDrawingBuffer(flush_identifier, LLUI_DISPLAY_getBufferAddress(&gc->image), false); + LLUI_DISPLAY_setBackBuffer(flush_identifier, LLUI_DISPLAY_getBufferAddress(&gc->image), false); } Serial Display @@ -1191,7 +1191,7 @@ Its aim is to prepare / configure the serial bus and data to transmit and then t The ``flush()`` function has to return as soon as possible. Before executing the next application drawing after a flush, the Graphics Engine automatically waits for the end of the serial data transmission: the back buffer (currently used by the serial device) is updated at the end of data transmission. -The serial device driver is responsible for unlocking the Graphics Engine by calling the function ``LLUI_DISPLAY_setDrawingBuffer()`` at the end of the transmission. +The serial device driver is responsible for unlocking the Graphics Engine by calling the function ``LLUI_DISPLAY_setBackBuffer()`` at the end of the transmission. There are two use cases: @@ -1237,7 +1237,7 @@ In that case, the serial driver must configure an interrupt to be notified about SERIAL_DRIVER_disable_interrupt(END_OF_COPY); // end of transmission, unlock the Graphics Engine without changing the back buffer address - LLUI_DISPLAY_setDrawingBuffer(_flush_identifier, back_buffer, true); // true: called under interrupt + LLUI_DISPLAY_setBackBuffer(_flush_identifier, back_buffer, true); // true: called under interrupt } **Software** @@ -1262,7 +1262,7 @@ A dedicated OS task is required to perform this transmission. SERIAL_DRIVER_transmit_data(back_buffer, LCD_WIDTH * LCD_HEIGHT * LCD_BPP / 8); // end of flush, unlock the Graphics Engine without changing the back buffer address - LLUI_DISPLAY_setDrawingBuffer(_flush_identifier, back_buffer, false); // false: called outside interrupt + LLUI_DISPLAY_setBackBuffer(_flush_identifier, back_buffer, false); // false: called outside interrupt } } @@ -1301,7 +1301,7 @@ Its aim is to prepare / configure the copy buffer process and then start the asy The ``flush()`` function has to return as soon as possible. Before executing the next application drawing after a flush, the Graphics Engine automatically waits for the end of the copy buffer process: the back buffer (currently used by the copy buffer process) is updated at the end of the copy. -The copy driver is responsible for unlocking the Graphics Engine by calling the function ``LLUI_DISPLAY_setDrawingBuffer()`` at the end of the copy. +The copy driver is responsible for unlocking the Graphics Engine by calling the function ``LLUI_DISPLAY_setBackBuffer()`` at the end of the copy. There are two use cases: @@ -1348,7 +1348,7 @@ In that case, the DMA driver must configure an interrupt to be notified about th DMA_DRIVER_disable_interrupt(END_OF_COPY); // end of copy, unlock the Graphics Engine without changing the back buffer address - LLUI_DISPLAY_setDrawingBuffer(_flush_identifier, back_buffer, true); // true: called under interrupt + LLUI_DISPLAY_setBackBuffer(_flush_identifier, back_buffer, true); // true: called under interrupt } **Software** @@ -1384,7 +1384,7 @@ A dedicated OS task is required to perform this copy. } // end of copy, unlock the Graphics Engine without changing the back buffer address - LLUI_DISPLAY_setDrawingBuffer(_flush_identifier, back_buffer, false); // false: called outside interrupt + LLUI_DISPLAY_setBackBuffer(_flush_identifier, back_buffer, false); // false: called outside interrupt } } @@ -1478,7 +1478,7 @@ There are two use cases: DMA_DRIVER_disable_interrupt(END_OF_COPY); // end of copy, unlock the Graphics Engine without changing the back buffer address - LLUI_DISPLAY_setDrawingBuffer(_flush_identifier, back_buffer, true); // true: called under interrupt + LLUI_DISPLAY_setBackBuffer(_flush_identifier, back_buffer, true); // true: called under interrupt } **Software** @@ -1511,7 +1511,7 @@ There are two use cases: } // end of copy, unlock the Graphics Engine without changing the back buffer address - LLUI_DISPLAY_setDrawingBuffer(_flush_identifier, back_buffer, false); // false: called outside interrupt + LLUI_DISPLAY_setBackBuffer(_flush_identifier, back_buffer, false); // false: called outside interrupt } } @@ -1562,7 +1562,7 @@ The first buffer is used by the application (buffer A), and the LCD controller u The LCD controller is reconfigured to use buffer A when the Graphics Engine is calling the ``flush()`` function. Before executing the next application drawing after a flush, the Graphics Engine automatically waits for the end of the flush buffer process: buffer B (currently used by the LDC controller) is updated at the end of the swap. -The LCD driver is responsible for unlocking the Graphics Engine by calling the function ``LLUI_DISPLAY_setDrawingBuffer()`` at the end of the swap. +The LCD driver is responsible for unlocking the Graphics Engine by calling the function ``LLUI_DISPLAY_setBackBuffer()`` at the end of the swap. .. code:: c @@ -1595,7 +1595,7 @@ The LCD driver is responsible for unlocking the Graphics Engine by calling the f // end of the swap, unlock the Graphics Engine, update the back buffer address uint8_t* new_back_buffer = (LCDC_get_address() == buffer_A) ? buffer_B : buffer_A; - LLUI_DISPLAY_setDrawingBuffer(_flush_identifier, new_back_buffer, true); // true: called under interrupt + LLUI_DISPLAY_setBackBuffer(_flush_identifier, new_back_buffer, true); // true: called under interrupt } .. _section_display_implementation: diff --git a/VEEPortingGuide/uiFontCore.rst b/VEEPortingGuide/uiFontCore.rst index 3cbf2fd95..26961f494 100644 --- a/VEEPortingGuide/uiFontCore.rst +++ b/VEEPortingGuide/uiFontCore.rst @@ -22,19 +22,30 @@ Memory Management The Font Renderer is able to load some fonts located outside the CPU addresses' space range. It uses the External Resource Loader. -When a font is located in such memory, the Font Renderer copies a very short part of the resource (the font file) into a RAM memory (into CPU addresses space range): the font header. -This header stays located in RAM until the application is using the font. -As soon as the application uses another external font, new font replaces the old one. -Then, on application demand, the Font Renderer loads some extra information from the font into the RAM memory (the font meta data, the font pixels, etc.). -This extra information is automatically unloaded from RAM when the Font Renderer no longer needs them. +When a font is located in such memory, the font characters are loaded one by one from the External Memory. -This extra information is stored into a RAM section called ``.bss.microui.display.externalFontsHeap``. +The Font Renderer uses a RAM buffer (External Font Heap) to only contain the font character currently being drawn by the application. +It is unloaded from RAM when the Font Renderer no longer needs it. + +The External Font Heap is stored into a RAM section called ``.bss.microui.display.externalFontsHeap``. Its size is automatically calculated according to the external fonts used by the firmware. -However it is possible to change this value by setting the application property ``ej.microui.memory.externalfontsheap.size``. +This size can be checked when enabling the verbose mode when building the application executable: + + .. figure:: images/font-external-font-heap.png + :alt: External Font Heap size in verbose mode + :align: center + + External Font Heap size in verbose mode + +However, it is possible to change this value by setting the application property ``ej.microui.memory.externalfontsheap.size``. This option is very useful when building a kernel: the kernel may anticipate the section size required by the features. .. warning:: When this size is smaller than the size required by an external font, some characters may be not drawn. +Also, the Font Renderer copies a very short part of the resource (the font file) in RAM (into CPU address space range): the font header. +This header remains located in RAM as long as the application is using the font. +As soon as the application uses another external font, the new font replaces the old one. + Configuration File ------------------ @@ -58,7 +69,7 @@ This chapter describes the steps to setup the loading of an external resource fr 9. The font loader looks for the font and only reads the font header. 10. (optional) The external resource is closed if the external resource is inside the CPU addresses' space range. 11. The application can use the font. -12. The external resource is never closed: the font's bytes are copied in RAM on demand (drawString, etc.). +12. The external resource is never closed: the font characters are retrieved one by one from External Memory on demand (drawString, etc.). Simulation ---------- diff --git a/VEEPortingGuide/uiImageGenerator.rst b/VEEPortingGuide/uiImageGenerator.rst index a533aa944..e34989bb7 100644 --- a/VEEPortingGuide/uiImageGenerator.rst +++ b/VEEPortingGuide/uiImageGenerator.rst @@ -76,7 +76,7 @@ To do that the Image Generator provides some services to implement. This chapter explain how to create and include this extension in the VEE Port. Next chapters explain the aim of each service. -1. Create a ``std-javalib`` project. The module name must start with the prefix ``imageGenerator`` (for instance ``imageGeneratorMyPlatform``). +1. Create a ``std-javalib`` project. The module name must start with the prefix ``imageGenerator`` (for instance ``imageGeneratorMyVEEPort``). 2. Add the dependency: .. code-block:: xml @@ -85,13 +85,13 @@ Next chapters explain the aim of each service. - Where ``x.y.z`` is the UI pack version used to build the VEE Port (minimum ``13.0.0``). The ``module.ivy`` should look like: + Where ``x.y.z`` is the UI Pack version used to build the VEE Port (minimum ``13.0.0``). The ``module.ivy`` should look like: .. code-block:: xml - + @@ -114,9 +114,9 @@ Next chapters explain the aim of each service. 3. Create the folder ``META-INF/services`` in source folder ``src/main/resources`` (this folder will be filled in later). -4. When a service is added (see next chapters), build the easyant project. -5. Copy the generated jar: ``target~/artifacts/imageGeneratorMyPlatform.jar`` in the VEE Port configuration project folder: ``MyPlatform-configuration/dropins/tools/`` -6. Rebuild the platform. +4. When a service is added (see next chapters), build the project. +5. Copy the generated jar: ``target~/artifacts/imageGeneratorMyVEEPort.jar`` in the VEE Port configuration project folder: ``MyVEEPort-configuration/dropins/tools/`` +6. Rebuild the VEE Port. .. _section_image_generator_test_extension_project: diff --git a/VEEPortingGuide/uiMigrationGuide.rst b/VEEPortingGuide/uiMigrationGuide.rst index 77512f74c..b39d5e25c 100644 --- a/VEEPortingGuide/uiMigrationGuide.rst +++ b/VEEPortingGuide/uiMigrationGuide.rst @@ -6,39 +6,146 @@ Migration Guide =============== -From 13.7.x to 14.0.0 +.. _section_ui_migrationguide_pack_14.0.2: + +From 14.0.1 to 14.0.2 +===================== + +BSP without GPU +""""""""""""""" + +* *[VEE Port configuration project]* + + * Set the dependency to the `C Module MicroUI 4.1.0`_. + * Delete the properties file ``cco_microui.properties``. + * Build the VEE Port. + +BSP with DMA2D +"""""""""""""" + +* *[VEE Port configuration project]* + + * Set the dependency to the `C Module MicroUI over DMA2D to version 6.0.0`_. + + * Notice that the name of the module changed from ``display-dma2d`` to ``microui-dma2d``, and that the module was moved to the :ref:`developer_repository`. + +* *[BSP project]* + + * In the directory ``ui``, delete the following files: + + * ``inc/ui_drawing_dma2d.h``, + * ``src/ui_drawing_dma2d.c``. + + * Delete the properties files ``cco_microui.properties`` and ``cco_display-dma2d.properties``. + * Build the VEE Port. + * Configure ``ui_dma2d/inc/ui_dma2d_configuration.h``, based on your previous settings in ``ui/inc/ui_drawing_dma2d_configuration.h``. + * Delete ``ui/inc/ui_dma2d_configuration.h``. + * Add the source files in ``ui_dma2d/src`` to the project. + * Add the path ``ui_dma2d/inc`` to the include path. + +BSP with VGLite +""""""""""""""" + +* *[VEE Port configuration project]* + + * Set the dependency to the `C Module MicroUI over VGLite to version 9.0.0`_. + +* *[BSP project]* + + * In the directory ``ui``, delete the following files: + + * ``inc/color.h``, + * ``inc/ui_drawing_vglite.h``, + * ``inc/ui_drawing_vglite_path.h``, + * ``inc/ui_drawing_vglite_process.h``, + * ``inc/ui_vglite.h``, + * ``src/ui_drawing_vglite.c``, + * ``src/ui_drawing_vglite_path.c``, + * ``src/ui_drawing_vglite_process.c``. + + * In the directory ``util``, delete the following files: + + * ``inc/mej_math.h``, + * ``src/mej_math.c``, + + * In ``LLUI_DISPLAY_IMPL_initialize``: + + * Call ``UI_VGLITE_initialize`` to initialize the VGLite controller and the VGLite library. + * Replace the call to ``UI_VGLITE_init`` with ``UI_VGLITE_start``. + + * Delete the properties files ``cco_microui.properties`` and ``cco_microui-vglite.properties``. + * Build the VEE Port. + * Configure ``ui_vglite/inc/ui_vglite_configuration.h``, based on your previous settings in ``ui/inc/ui_vglite_configuration.h``. + * Delete ``ui/inc/ui_vglite_configuration.h``. + * Add the source files in ``ui_vglite/src`` to the project. + * Add the path ``ui_vglite/inc`` to the include path. + +BSP with NemaGFX +"""""""""""""""" + +* *[VEE Port configuration project]* + + * Set the dependency to the `C Module MicroUI over NemaGFX to version 3.0.0`_. + +* *[BSP project]* + + * Delete ``ui/src/ui_drawing_nema.c``. + * Replace the following calls with the new function names: + + * ``UI_DRAWING_NEMA_initialize`` becomes ``UI_NEMA_initialize``, + * ``UI_DRAWING_NEMA_post_operation`` becomes ``UI_NEMA_post_operation``, + * ``UI_DRAWING_NEMA_configure_memcpy`` becomes ``UI_NEMA_configure_memcpy``, + * ``UI_DRAWING_NEMA_start_memcpy`` becomes ``UI_NEMA_start_memcpy``. + + * Delete the properties files ``cco_microui.properties`` and ``cco_microui-nemagfx.properties``. + * Build the VEE Port. + * Configure ``ui_nemagfx/inc/ui_nema_configuration.h``, based on your previous settings in ``ui/inc/ui_drawing_nema_configuration.h``. + * Add the source files in ``ui_nemagfx/src`` to the project. + * Add the path ``ui_nemagfx/inc`` to the include path. + * If you were using the task mode, switch to interrupt mode. + + * Remove your implementation of ``UI_DRAWING_NEMA_IMPL_operation_submitted``. + * Remove the task that called ``UI_DRAWING_NEMA_post_operation``. + * Look for any use of the macro ``NEMA_INTERRUPT_MODE``, which denotes a differentiation between the task mode and the interrupt mode. + This macro is no longer used. + Adjust your code so that only the code targeting the interrupt mode remains. + * Follow the steps detailed in the section :ref:`section_ui_c_module_microui_nemagfx_implementation`. + +From 13.7.x to 14.0.1 ===================== Front Panel """"""""""" -* Fetch `Front Panel Widgets 4.0.0`_ (it fetches by transitivity the `UI Pack 14.0.0`_): +* Fetch `Front Panel Widgets 4.0.1`_ (it fetches by transitivity the `UI Pack 14.0.1`_): .. code-block:: xml - - + + * Re-organize imports of all Java classes (classes ``MicroUIImageFormat``, ``MicroUIImage`` and ``MicroUIGraphicsContext`` have been extracted from ``LLUIPainter``). +* Remove all calls to ``MicroUIGraphicsContext.setDrawingLimits``. This method has been removed as it is no longer needed. * The ``doubleBufferFeature`` attribute has been removed from the ``Display`` widget. The ``bufferPolicyClass`` replaces it (see :ref:`Buffer Refresh Strategy on the Simulator`). .. code-block:: xml - + * The ``FlushVisualizerDisplay`` widget has been merged with the ``Display`` widget. To use this functionality, use the ``Display`` widget instead of the ``FlushVisualizerDisplay`` widget in the Front Panel ``.fp`` file and set the option ``ej.fp.display.flushVisualizer=true`` in the options of the application launcher. -.. _Front Panel Widgets 4.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/ej/tool/frontpanel/widget/4.0.0/ -.. _UI Pack 14.0.0: https://repository.microej.com/modules/com/microej/pack/ui/ui-pack/14.0.0/ +.. _Front Panel Widgets 4.0.1: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/ej/tool/frontpanel/widget/4.0.1/ +.. _UI Pack 14.0.1: https://repository.microej.com/modules/com/microej/pack/ui/ui-pack/14.0.1/ +.. _section_ui_migrationguide_pack_14.0.1_bsp_without_gpu: BSP Without GPU """"""""""""""" * *[VEE Port configuration project]* - * Fetch the `C Module MicroUI 4.0.0`_. + * Fetch the `C Module MicroUI 4.0.1`_. * *[BSP project]* @@ -49,113 +156,113 @@ BSP Without GPU * Comment the line ``#error "This header must [...]"``. * The next actions depend on the available numbers of buffers allocated in the MCU memories and if the front buffer is mapped on an MCU's buffer (if not, that means the LCD device owns a buffer). The following table redirects the next steps according to the display connection with the MCU: - .. table:: Copy and/or Swap actions + .. table:: Transmit and/or Swap actions +---------+--------+----------------------------------+ | Buffers | Mapped | Next Actions | +=========+========+==================================+ - | 2 (1+1) | no | *[Display "Copy"]* | + | 2 (1+1) | no | *[Display "Transmit"]* | +---------+--------+----------------------------------+ | 2 | yes | *[Display "Swap double buffer"]* | +---------+--------+----------------------------------+ | 3 | yes | *[Display "Swap triple buffer"]* | +---------+--------+----------------------------------+ - | 3 (2+1) | no | *[Display "Copy and Swap"]* | + | 3 (2+1) | no | *[Display "Transmit and Swap"]* | +---------+--------+----------------------------------+ -* *[Display "Copy"]* +* *[Display "Transmit"]* * Set the value of the define ``UI_DISPLAY_BRS``: ``UI_DISPLAY_BRS_SINGLE``. * Set the value of the define ``UI_DISPLAY_BRS_DRAWING_BUFFER_COUNT``: ``1``. * Uncomment the define ``UI_DISPLAY_BRS_FLUSH_SINGLE_RECTANGLE``. * Change the signature and the implementation of the function flush: ``void LLUI_DISPLAY_IMPL_flush(MICROUI_GraphicsContext* gc, uint8_t flush_identifier, const ui_rect_t regions[], size_t length)`` - + * Store (in a static field) the rectangle to flush (the array contains only one rectangle). * Store (in a static field) the flush identifier. - * Unlock (immediately or wait for the LCD tearing signal interrupt) the *flush task* (hardware or software) that will flush (copy or transmit) the back buffer data to the front buffer. + * Unlock (immediately or wait for the LCD tearing signal interrupt) the *flush task* (hardware or software) that will transmit the back buffer data to the front buffer. * Remove the returned value (the back buffer address). - - * At the end of the flush (in an interrupt or at the end of the software *flush task*), replace the call to ``LLUI_DISPLAY_flushDone()`` with ``LLUI_DISPLAY_setDrawingBuffer()``: it will unlock the Graphics Engine. Give the back buffer address (same address as at start-up) and the flush identifier. + + * At the end of the flush (in an interrupt or at the end of the software *flush task*), replace the call to ``LLUI_DISPLAY_flushDone()`` with ``LLUI_DISPLAY_setBackBuffer()``: it will unlock the Graphics Engine. Give the back buffer address (same address as at start-up) and the flush identifier. * *[Display "Swap double buffer"]* * Set the value of the define ``UI_DISPLAY_BRS``: ``UI_DISPLAY_BRS_PREDRAW``. * Set the value of the define ``UI_DISPLAY_BRS_DRAWING_BUFFER_COUNT``: ``2``. * Change the signature and the implementation of the function flush: ``void LLUI_DISPLAY_IMPL_flush(MICROUI_GraphicsContext* gc, uint8_t flush_identifier, const ui_rect_t regions[], size_t length)`` - + * Store (in a static field) the back buffer address (`LLUI_DISPLAY_getBufferAddress(&gc->image)`). * Store (in a static field) the flush identifier. * Unlock (immediately or wait for the LCD tearing signal interrupt) the *swap task* (hardware or software) that will swap the back buffer and the front buffer. * Remove the static fields ``ymin`` and ``ymax`` (now useless). * Remove the returned value (the back buffer address). - + * Case of *hardware swap* (LCD *swap* interrupt): change the implementation of the LCD *swap* interrupt: * Remove all the code concerning the post-flush restoration (remove the *flush task* or the use of a DMA). In both cases, the call to ``LLUI_DISPLAY_flushDone()`` is removed. - * Unlock the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the new back buffer address and the flush identifier. - + * Unlock the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the new back buffer address and the flush identifier. + * Case of *software swap* (dedicated *swap task*): change the task actions: * Swap back and front buffers. * Wait for the end of the buffers swap: ensure the LCD driver does not use the old front buffer anymore. * Remove all the code concerning the post-flush restoration (the call to ``memcpy`` or the use of a DMA). In both cases, the call to ``LLUI_DISPLAY_flushDone()`` is removed. - * Unlock the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the new back buffer address and the flush identifier. - + * Unlock the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the new back buffer address and the flush identifier. + * *[Display "Swap triple buffer"]* * Set the value of the define ``UI_DISPLAY_BRS``: ``UI_DISPLAY_BRS_PREDRAW``. * Set the value of the define ``UI_DISPLAY_BRS_DRAWING_BUFFER_COUNT``: ``3``. * Change the signature and the implementation of the function flush: ``void LLUI_DISPLAY_IMPL_flush(MICROUI_GraphicsContext* gc, uint8_t flush_identifier, const ui_rect_t regions[], size_t length)`` - + * Store (in a static field) the back buffer address (`LLUI_DISPLAY_getBufferAddress(&gc->image)`). * Store (in a static field) the flush identifier. * Unlock (immediately or wait for the LCD tearing signal interrupt) the *swap task* that will swap the buffers. * Remove the static fields ``ymin`` and ``ymax`` (now useless). * Remove the returned value (the back buffer address). - + * In the *swap task*: change the task actions: * Swap buffers. * Remove all the code concerning the post-flush restoration (the call to ``memcpy`` or the use of a DMA). In both cases, the call to ``LLUI_DISPLAY_flushDone()`` is removed. - * Unlock the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the new back buffer address and the flush identifier (the Graphics Engine can be unlocked immediately because a buffer is freed for sure). + * Unlock the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the new back buffer address and the flush identifier (the Graphics Engine can be unlocked immediately because a buffer is freed for sure). * Wait for the end of the buffers swap: ensure the LCD driver does not use the old front buffer anymore. -* *[Display "Copy and Swap"]* +* *[Display "Transmit and Swap"]* * Set the value of the define ``UI_DISPLAY_BRS``: ``UI_DISPLAY_BRS_PREDRAW``. * Set the value of the define ``UI_DISPLAY_BRS_DRAWING_BUFFER_COUNT``: ``2``. - * Uncomment the define ``UI_DISPLAY_BRS_FLUSH_SINGLE_RECTANGLE``. + * Uncomment the define ``UI_DISPLAY_BRS_FLUSH_SINGLE_RECTANGLE``. * Change the signature and the implementation of the function flush: ``void LLUI_DISPLAY_IMPL_flush(MICROUI_GraphicsContext* gc, uint8_t flush_identifier, const ui_rect_t regions[], size_t length)`` - + * Store (in a static field) the rectangle to flush (the array contains only one rectangle). * Store (in a static field) the back buffer address (`LLUI_DISPLAY_getBufferAddress(&gc->image)`). * Store (in a static field) the flush identifier. - * Unlock (immediately or wait for the LCD tearing signal interrupt) the *copy & swap task* that will flush (copy or transmit) the current back buffer data to the front buffer, and that will swap the back buffers. + * Unlock (immediately or wait for the LCD tearing signal interrupt) the *transmit & swap task* that will transmit the current back buffer data to the front buffer, and that will swap the back buffers. * Remove the returned value (the back buffer address). - - * In the *copy & swap task*: change the "copy & swap" actions: + + * In the *transmit & swap task*: change the "transmit & swap" actions: * Start the transmission of the current back buffer (called *buffer A*) data to the front buffer. * Swap back *buffer A* and back *buffer B*. * Wait for the end of the back buffers swap: ensure the LCD driver is now using the *buffer A* as the *transmission* buffer. * Remove all the code concerning to the post-flush restoration (the call to ``memcpy`` or the use of a DMA). In both cases, the call to ``LLUI_DISPLAY_flushDone()`` is removed. - * Unlock the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the back *buffer B* address and the flush identifier. + * Unlock the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the back *buffer B* address and the flush identifier. * Wait for the end of the *transmission*: ensure the LCD driver has finished to flush the data. - * (optional) Unlock again the Graphics Engine by calling ``LLUI_DISPLAY_setDrawingBuffer()``, giving the *buffer A* address and the flush identifier: + * (optional) Unlock again the Graphics Engine by calling ``LLUI_DISPLAY_setBackBuffer()``, giving the *buffer A* address and the flush identifier: + + * The call to ``LLUI_DISPLAY_setBackBuffer()`` returns ``false``: that means at least one drawing has been performed in the *buffer B*; there is nothing else to do. + * The call to ``LLUI_DISPLAY_setBackBuffer()`` returns ``true``: that means no drawing has started yet in the *buffer B*. In that case, the Graphics Engine will reuse the *buffer A* as a back buffer, and the *restoration of the past* becomes useless. The back buffers swap is so canceled; update the LCD driver status in consequence. - * The call to ``LLUI_DISPLAY_setDrawingBuffer()`` returns ``false``: that means at least one drawing has been performed in the *buffer B*; there is nothing else to do. - * The call to ``LLUI_DISPLAY_setDrawingBuffer()`` returns ``true``: that means no drawing has started yet in the *buffer B*. In that case, the Graphics Engine will reuse the *buffer A* as a back buffer, and the *restoration of the past* becomes useless. The back buffers swap is so canceled; update the LCD driver status in consequence. - BSP with DMA2D """""""""""""" * *[VEE Port configuration project]* - * Fetch the `C Module DMA2D 5.0.0`_. + * Fetch the `C Module DMA2D 5.0.1`_. * *[BSP project]* - * Follow the migration steps of "BSP without GPU". + * **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.0.1_bsp_without_gpu`. * Check the content of the configuration file ``ui_drawing_dma2d_configuration.h`` (a versioning has been added). * Comment the line ``#error [...]"``. * According to the display :ref:`section_brs`, unlock the MicroUI Graphics Engine in the LCD interrupt or the DMA2D memcpy callback (see :ref:`section_ui_c_module_microui_dma2d`). @@ -167,18 +274,18 @@ BSP with VGLite * *[VEE Port configuration project]* - * Fetch the `C Module VGLite 8.0.0`_. + * Fetch the `C Module VGLite 8.0.1`_. * *[BSP project]* - * Follow the migration steps of "BSP without GPU". + * **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.0.1_bsp_without_gpu`. * Migrate VGLite library to the version **3.0.15_rev7**. * Modify the VGLite library **3.0.15_rev7** by applying the patch ``3.0.15_rev7.patch`` (see README.md near the patch file for more information). * In the file ``vglite_window.c``, add the function ``VGLITE_CancelSwapBuffers()`` and its prototype in ``vglite_window.h``: .. code-block:: c - void VGLITE_CancelSwapBuffers(void) { + void VGLITE_CancelSwapBuffers(void) { fb_idx = fb_idx == 0 ? (APP_BUFFER_COUNT - 1) : (fb_idx ) - 1; } @@ -187,11 +294,11 @@ BSP with NemaGFX * *[VEE Port configuration project]* - * Fetch the `C Module NemaGFX 2.0.0`_. + * Fetch the `C Module NemaGFX 2.0.1`_. * *[BSP project]* - * Follow the migration steps of "BSP without GPU". + * **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.0.1_bsp_without_gpu`. * Check the content of the configuration file ``ui_drawing_nema_configuration.h`` (new version ``2``). From 13.6.x to 13.7.2 @@ -210,6 +317,8 @@ Front Panel .. _UI Pack 13.7.2: https://repository.microej.com/modules/com/microej/pack/ui/ui-pack/13.7.2/ +.. _section_ui_migrationguide_pack_13.7.2_bsp_without_gpu: + BSP without GPU """"""""""""""" @@ -230,7 +339,7 @@ BSP with DMA2D * *[BSP project]* - * Follow the migration steps of "BSP without GPU". + * **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.7.2_bsp_without_gpu`. BSP with VGLite """""""""""""""" @@ -241,7 +350,7 @@ BSP with VGLite * *[BSP project]* - * Follow the migration steps of "BSP without GPU". + * **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.7.2_bsp_without_gpu`. BSP with NemaGFX """""""""""""""" @@ -252,7 +361,7 @@ BSP with NemaGFX * *[BSP project]* - * Follow the migration steps of "BSP without GPU". + * **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.7.2_bsp_without_gpu`. * Review all options of ``ui_drawing_nema_configuration.h`` (version ``2``). From 13.5.x to 13.6.2 @@ -264,7 +373,7 @@ Front Panel * (optional) Fetch `Front Panel Widgets 3.0.0`_ to use the new features of the Front Panel Widget library: .. code-block:: xml - + * (optional) Fetch explicitly the `UI Pack 13.6.2`_ to use the new API of the UI Pack: @@ -289,12 +398,12 @@ These steps are for a VEE Port that manages its own implementation of ``LLUI_DIS * Fetch the `C Module VGLite 7.1.0`_. * (optional) Fetch `C Module RT500 7.0.0`_ - + * *[BSP project]* * Delete the properties file ``cco_microui-vglite.properties``. - * Delete the following files from the file-system and from the C project configuration: - + * Delete the following files from the file-system and from the C project configuration: + - ``inc/display_utils.h`` - ``inc/display_vglite.h`` - ``inc/drawing_vglite.h`` @@ -305,12 +414,12 @@ These steps are for a VEE Port that manages its own implementation of ``LLUI_DIS - ``src/drawing_vglite.c`` - ``src/vglite_path.c`` - * Add the new files to the C project configuration: - + * Add the new files to the C project configuration: + - ``src/ui_drawing_vglite_path.c`` - ``src/ui_drawing_vglite_process.c`` - ``src/ui_vglite.c`` - + * Review all imports of the removed header files. * In the implementation of ``LLUI_DISPLAY_impl.h``, call ``UI_VGLITE_init()`` during the initialization step. * In the GPU interrupt rountine, call ``UI_VGLITE_IRQHandler()``. @@ -333,7 +442,7 @@ These steps are for a VEE Port that uses the implementation of ``LLUI_DISPLAY_im * Fetch the `C Module VGLite 7.1.0`_. * Fetch `C Module RT500 7.0.0`_ - + * *[BSP project]* * Follow the steps of :ref:`section_ui_migrationguide_13.6_vglite` (described above) except the calls to ``UI_VGLITE_init()`` and ``UI_VGLITE_IRQHandler()``. @@ -345,12 +454,12 @@ BSP with NemaGFX * *[VEE Port configuration project]* * Fetch the `C Module NemaGFX 1.0.0`_. - + * *[BSP project]* * Add all the C files available in ``src`` folder. * Configure the C project to include the ``inc`` folder. - * Read the comments in ``ui_drawing_nema_configuration.h`` and configures the C module. + * Read the comments in ``ui_drawing_nema_configuration.h`` and configure the C module. From 13.4.x to 13.5.1 ===================== @@ -376,6 +485,8 @@ Front Panel .. _UI Pack 13.5.1: https://repository.microej.com/modules/com/microej/pack/ui/ui-pack/13.5.1/ +.. _section_ui_migrationguide_pack_13.5.1_bsp_without_gpu: + BSP without GPU """"""""""""""" @@ -392,7 +503,7 @@ BSP without GPU BSP with DMA2D """""""""""""" -* Follow the migration steps of "BSP without GPU". +* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.5.1_bsp_without_gpu`. * *[VEE Port configuration project]* * Fetch the `C Module DMA2D 4.0.0`_. @@ -412,16 +523,16 @@ BSP with DMA2D BSP with VGLite """""""""""""""" -.. note:: +.. note:: The C Module is designed to target the `NXP i.MX RT500`_; however it can be locally customized for other boards (see :ref:`[Custom project]`) -* Follow the migration steps of "BSP without GPU". +* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.5.1_bsp_without_gpu`. * *[VEE Port configuration project]* * Fetch the `C Module VGLite 6.0.1`_. - + * *[BSP project]* - + * Delete the properties file ``cco_microui-vglite.properties``. * Delete the C files ``vg_drawer.h`` and ``vg_drawer.c`` and remove them from the C project configuration. * Verify the options in ``display_configuration.h``. @@ -430,6 +541,8 @@ BSP with VGLite From 13.3.x to 13.4.1 ===================== +.. _section_ui_migrationguide_pack_13.4.1_bsp_without_gpu: + BSP without GPU """"""""""""""" @@ -444,7 +557,7 @@ BSP without GPU BSP with DMA2D """""""""""""" -* Follow the migration steps of "BSP without GPU". +* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.4.1_bsp_without_gpu`. * *[VEE Port configuration project]* * Fetch the `C Module DMA2D 3.0.2`_. @@ -456,10 +569,10 @@ BSP with DMA2D BSP with VGLite """""""""""""""" -.. note:: +.. note:: The C Module is designed to target the `NXP i.MX RT500`_; however it can be locally customized for other boards (see :ref:`[Custom project]`) -* Follow the migration steps of "BSP without GPU". +* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.4.1_bsp_without_gpu`. * *[VEE Port configuration project]* * Fetch the `C Module VGLite 5.0.1`_. @@ -483,6 +596,8 @@ Front Panel +.. _section_ui_migrationguide_pack_13.3.1_bsp_without_gpu: + BSP without GPU """"""""""""""" @@ -497,7 +612,7 @@ BSP without GPU BSP with DMA2D """""""""""""" -* Follow the migration steps of "BSP without GPU". +* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.3.1_bsp_without_gpu`. * *[VEE Port configuration project]* * Fetch the `C Module DMA2D 3.0.0`_. @@ -509,10 +624,10 @@ BSP with DMA2D BSP with VGLite """""""""""""""" -.. note:: +.. note:: The C Module is designed to target the `NXP i.MX RT500`_; however it can be locally customized for other boards (see :ref:`[Custom project]`). -* Follow the migration steps of "BSP without GPU". +* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.3.1_bsp_without_gpu`. * *[VEE Port configuration project]* * Fetch the `C Module VGLite 3.0.0`_. @@ -557,7 +672,7 @@ Front Panel * (optional) Fetch `Front Panel Widgets 2.1.0`_ to use the new features of the Front Panel Widget library (it fetches by transitivity the `UI Pack 13.1.0`_): .. code-block:: xml - + * (optional) Or fetch explicitly the `UI Pack 13.1.0`_ to use the new API of the UI Pack: @@ -568,6 +683,8 @@ Front Panel +.. _section_ui_migrationguide_pack_13.1.0_bsp_without_gpu: + BSP without GPU """"""""""""""" @@ -587,7 +704,7 @@ BSP without GPU BSP with DMA2D """""""""""""" -* Follow the migration steps of "BSP without GPU". +* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_13.1.0_bsp_without_gpu`. * *[VEE Port configuration project]* * Fetch the `C Module DMA2D 2.1.0`_. @@ -606,7 +723,7 @@ VEE Port Configuration Project """""""""""""""""""""""""""""" * Update Architecture version: 7.16.0 or higher. -* Add `the following module `__ in the :ref:`module description file `: +* Add `the following module `__ in the :ref:`module description file `: .. code-block:: xml @@ -618,10 +735,10 @@ Hardware Accelerator """""""""""""""""""" * Open :guilabel:`-configuration` project > :guilabel:`display` > :guilabel:`display.properties` -* Remove optional property ``hardwareAccelerator``. If old value was ``dma2d``, add `the following module `__ in the :ref:`module description file `: - +* Remove optional property ``hardwareAccelerator``. If old value was ``dma2d``, add `the following module `__ in the :ref:`module description file `: + .. code-block:: xml - + * For the hardware accelerator DMA2D, please consult STM32F7Discovery board updates. Add the file ``lldisplay_dma2d.c``, the global defines ``DRAWING_DMA2D_BPP=16`` (or another value) and ``STM32F4XX`` or ``STM32F7XX`` @@ -637,7 +754,7 @@ The available changes in Front Panel API are described in :ref:`next chapter * ``ej.fp.event.MicroUIButtons`` has been renamed in ``ej.microui.event.EventButton``, and all others ``ej.fp.event.MicroUIxxx`` in ``ej.microui.event.Eventxxx`` @@ -727,7 +844,7 @@ Front Panel API * [Added] ``MicroUIGraphicsContext#requestDrawing()``: allows to take the hand on the back buffer. * [Added] ``MicroUIImage``: representation of a MicroUI `Image`_ in front panel. This interface (implemented by the Graphics Engine) provides several function to get information on image. * [Added] ``setDrawer(UIDrawing)``: allows to configure the implementation of ``UIDrawing`` the ``LLUIPainter`` has to use. When no drawer is configured, ``LLUIPainter`` redirects all drawings to the internal Graphics Engine software algorithms. - * + * ``ej.microui.display.UIDrawing`` * [Added] Equivalent of ``ui_drawing.h`` and ``ui_drawing_soft.h**``: allows to implement some drawing algorithms and/or to use the ones provided by the Graphics Engine. The drawing methods are related to the library ``ej.api.microui``. @@ -792,10 +909,10 @@ This project must be updated. - + - + @@ -804,9 +921,9 @@ This project must be updated. - + - + @@ -839,7 +956,7 @@ Image Generator API * ``com.is2t.microej.microui.image.DisplayExtension`` - * [Removed] + * [Removed] * ``com.is2t.microej.microui.image.GenericDisplayExtension`` @@ -883,7 +1000,7 @@ The available changes in LLAPI are described in :ref:`next chapter`_ - `1.0.4 `_ * - [13.7.0-13.7.2] @@ -124,7 +124,7 @@ Display +-----------------+------------------------------------------------------------------+ | UI Pack Range | Changes | +=================+==================================================================+ -| 14.0.0 | Signature of ``LLUI_DISPLAY_IMPL_flush()`` changed. | +| [14.0.0-14.0.2] | Signature of ``LLUI_DISPLAY_IMPL_flush()`` changed. | +-----------------+------------------------------------------------------------------+ | [13.0.0-13.7.2] | *UI3* format: implement ``LLUI_DISPLAY_impl.h``: | | | | @@ -157,7 +157,7 @@ Input +-----------------+------------------------------------------------------------------+ | UI Pack Range | Changes | +=================+==================================================================+ -| [13.0.0-14.0.0] | *UI3* format: implement ``LLUI_INPUT_impl.h``: | +| [13.0.0-14.0.2] | *UI3* format: implement ``LLUI_INPUT_impl.h``: | | | | | | * ``void LLUI_INPUT_IMPL_initialize([...]);`` | | | * ``jint LLUI_INPUT_IMPL_getInitialStateValue([...]);`` | @@ -178,7 +178,7 @@ LED +-----------------+------------------------------------------------------------------+ | UI Pack Range | Changes | +=================+==================================================================+ -| [13.0.0-13.7.2] | *UI3* format: implement ``LLUI_LED_impl.h``: | +| [13.0.0-14.0.2] | *UI3* format: implement ``LLUI_LED_impl.h``: | | | | | | * ``jint LLUI_LED_IMPL_initialize([...]);`` | | | * ``jint LLUI_LED_IMPL_getIntensity([...]);`` | @@ -205,7 +205,7 @@ The Front Panel project must fetch the widgets compatible with the MicroEJ UI Pa +-----------------+--------------------------------------------+-----------------+ | UI Pack Range | Module | Version | +=================+============================================+=================+ -| [13.0.0-14.0.0] | `com.microej.pack.ui.ui-pack(frontpanel)`_ | [13.0.0-14.0.0] | +| [13.0.0-14.0.2] | `com.microej.pack.ui.ui-pack(frontpanel)`_ | [13.0.0-14.0.2] | +-----------------+--------------------------------------------+-----------------+ | [12.0.0-12.1.5] | `ej.tool.frontpanel.widget-microui`_ | 1.0.0 | +-----------------+--------------------------------------------+-----------------+ @@ -221,7 +221,7 @@ When the Front Panel project does not require/use the latest Front Panel UI API, +---------------------+-----------------------------+--------------+ | Widget Module Range | UI Pack Compatibility Range | Repository | +=====================+=============================+==============+ -| 4.0.0 | 14.0.0 | `Developer`_ | +| [4.0.0-4.0.1] | [14.0.0-14.0.2] | `Developer`_ | +---------------------+-----------------------------+--------------+ | 3.0.0 | [13.5.1-10-13.7.2] | `Developer`_ | +---------------------+-----------------------------+--------------+ @@ -252,7 +252,7 @@ The module version is the MicroEJ Generic UI Pack version, that is always aligne +-----------------+-------------------------------------------------+-------------------+ | UI Pack Range | Module | Version | +=================+=================================================+===================+ -| [13.0.0-14.0.0] | `com.microej.pack.ui.ui-pack(imagegenerator)`_ | [13.0.0-14.0.0] | +| [13.0.0-14.0.2] | `com.microej.pack.ui.ui-pack(imagegenerator)`_ | [13.0.0-14.0.2] | +-----------------+-------------------------------------------------+-------------------+ .. note:: Before MicroEJ UI Pack ``13.0.0``, the Image Generator extension project must depend on classpath variable ``IMAGE-GENERATOR-x.x``. @@ -270,53 +270,62 @@ MicroUI C Module The MicroUI C module `com.microej.clibrary.llimpl(microui)`_ is available on MicroEJ Central Repository, see :ref:`section_ui_cco`. The following table describes the compatibility versions between the MicroEJ UI Packs and the C modules: -+-----------------+----------------+------------------------------------------+ -| UI Pack Range | C Module Range | Comment | -+=================+================+==========================================+ -| 14.0.0 | 4.0.0 | buffer refresh strategies | -+-----------------+----------------+------------------------------------------+ -| [13.7.0-13.7.2] | 3.1.0 | free image resources | -+-----------------+----------------+------------------------------------------+ -| [13.5.0-13.6.2] | 3.0.0 | multiple Graphics Context output formats | -+-----------------+----------------+------------------------------------------+ -| [13.3.0-13.4.1] | [2.0.0-2.0.1] | copy and draw image | -+-----------------+----------------+------------------------------------------+ -| [13.1.0-13.2.0] | [1.1.0-1.1.1] | image heap, events queue, drawing limits | -+-----------------+----------------+------------------------------------------+ -| [13.0.0-13.1.0] | [1.0.0-1.0.3] | | -+-----------------+----------------+------------------------------------------+ ++-----------------+------------------+------------------------------------------+ +| UI Pack | MicroUI C Module | Comment | ++=================+==================+==========================================+ +| [14.0.0-14.0.2] | [4.0.0-4.1.0] | Buffer refresh strategies | ++-----------------+------------------+------------------------------------------+ +| [13.7.0-13.7.2] | [3.1.0-3.1.1] | Free image resources | ++-----------------+------------------+------------------------------------------+ +| [13.5.0-13.6.2] | 3.0.0 | Multiple Graphics Context output formats | ++-----------------+------------------+------------------------------------------+ +| [13.3.0-13.4.1] | [2.0.0-2.0.1] | Copy and draw image | ++-----------------+------------------+------------------------------------------+ +| [13.1.0-13.2.0] | [1.1.0-1.1.1] | Image heap, events queue, drawing limits | ++-----------------+------------------+------------------------------------------+ +| [13.0.0-13.0.7] | 1.0.3 | | ++-----------------+------------------+------------------------------------------+ .. _com.microej.clibrary.llimpl(microui): https://repository.microej.com/modules/com/microej/clibrary/llimpl/microui/ +.. _section_ui_releasenotes_cmodule_extended: + Extended C Modules """""""""""""""""" Some C modules extend the main MicroUI C module. They override the default implementation to use a GPU to perform some drawings. Contrary to the main MicroUI C module, they are optional: when they are not available, the default implementation of drawings is used. -The default implementations use the Graphics Engine software algorithms. +The default implementation uses the Graphics Engine software algorithms. **STM32 Chrom-ART** The :ref:`DMA2D C module ` targets the STM32 CPU that provides the Chrom-ART accelerator. +.. note:: Since version 6.0.0, this module has been moved from the MicroEJ `DMA2D_Central`_ Repository to the MicroEJ `DMA2D_Developer`_ Repository. + The following table describes the version compatibility between the MicroEJ UI Packs and the C modules: -+-----------------+----------------+------------------------------------------+ -| UI Pack Range | C Module Range | Comment | -+=================+================+==========================================+ -| 14.0.0 | 5.0.0 | buffer refresh strategies | -+-----------------+----------------+------------------------------------------+ -| [13.7.0-13.7.2] | 4.1.0 | free image resources | -+-----------------+----------------+------------------------------------------+ -| [13.5.0-13.6.2] | 4.0.0 | multiple Graphics Context output formats | -+-----------------+----------------+------------------------------------------+ -| [13.3.0-13.4.1] | [3.0.0-3.0.2] | copy and draw image | -+-----------------+----------------+------------------------------------------+ -| [13.1.0-13.2.0] | [2.0.0-2.1.0] | drawing limits | -+-----------------+----------------+------------------------------------------+ -| [13.0.0-13.0.7] | [1.0.6-1.0.8] | | -+-----------------+----------------+------------------------------------------+ ++-----------------+---------------+------------------+------------------------------------------+ +| UI Pack | Chrom-ART | MicroUI C Module | Comment | ++=================+===============+==================+==========================================+ +| [14.0.1-14.0.2] | [5.0.1-6.0.0] | [4.0.1-4.1.0] | C modules harmonization | ++-----------------+---------------+------------------+------------------------------------------+ +| 14.0.0 | 5.0.0 | 4.0.0 | Buffer refresh strategies | ++-----------------+---------------+------------------+------------------------------------------+ +| [13.7.0-13.7.2] | 4.1.0 | [3.1.0-3.1.1] | Free image resources | ++-----------------+---------------+------------------+------------------------------------------+ +| [13.5.1-13.6.2] | 4.0.0 | 3.0.0 | Multiple Graphics Context output formats | ++-----------------+---------------+------------------+------------------------------------------+ +| [13.3.0-13.4.1] | [3.0.0-3.0.2] | [2.0.0-2.0.1] | Copy and draw image | ++-----------------+---------------+------------------+------------------------------------------+ +| [13.1.0-13.2.0] | [2.0.0-2.1.0] | [1.1.0-1.1.1] | Drawing limits | ++-----------------+---------------+------------------+------------------------------------------+ +| [13.0.0-13.0.7] | [1.0.6-1.0.8] | 1.0.3 | | ++-----------------+---------------+------------------+------------------------------------------+ + +.. _DMA2D_Central: https://repository.microej.com/modules/com/microej/clibrary/llimpl/display-dma2d/ +.. _DMA2D_Developer: https://forge.microej.com/ui/native/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-dma2d/ **Vivante VGLite** @@ -324,25 +333,29 @@ The :ref:`VGLite C module ` targets the NXP The following table describes the version compatibility between the MicroEJ UI Packs and the C modules: -+-----------------+----------------+------------------------------------------+ -| UI Pack Range | C module Range | Comment | -+=================+================+==========================================+ -| 14.0.0 | 8.0.0 | buffer refresh strategies | -+-----------------+----------------+------------------------------------------+ -| [13.7.0-13.7.2] | 7.2.0 | free image resources | -+-----------------+----------------+------------------------------------------+ -| [13.5.0-13.6.2] | [6.0.0-7.1.0] | multiple Graphics Context output formats | -+-----------------+----------------+------------------------------------------+ -| [13.3.0-13.4.1] | [3.0.0-5.0.1] | copy and draw image | -+-----------------+----------------+------------------------------------------+ -| [13.1.0-13.2.0] | [1.0.0-2.0.0] | | -+-----------------+----------------+------------------------------------------+ ++-----------------+---------------+------------------+------------------------------------------+ +| UI Pack | VGLite | MicroUI C Module | Comment | ++=================+===============+==================+==========================================+ +| [14.0.1-14.0.2] | 9.0.0 | 4.1.0 | VG Pack extensibility | ++-----------------+---------------+------------------+------------------------------------------+ +| [14.0.1-14.0.2] | 8.0.1 | 4.0.1 | C modules harmonization | ++-----------------+---------------+------------------+------------------------------------------+ +| 14.0.0 | 8.0.0 | 4.0.0 | Buffer refresh strategies | ++-----------------+---------------+------------------+------------------------------------------+ +| [13.7.0-13.7.2] | 7.2.0 | [3.1.0-3.1.1] | Free image resources | ++-----------------+---------------+------------------+------------------------------------------+ +| [13.5.1-13.6.2] | [6.0.0-7.1.0] | 3.0.0 | Multiple Graphics Context output formats | ++-----------------+---------------+------------------+------------------------------------------+ +| [13.3.0-13.4.1] | [3.0.0-5.0.1] | [2.0.0-2.0.1] | | ++-----------------+---------------+------------------+------------------------------------------+ The following table describes the version compatibility between the C module and the VGLite libraries (officially supported): +----------------+-----------------------------+ | C Module Range | VGLite Libraries Range | +================+=============================+ +| [8.0.0-9.0.0] | 3.0.15_rev7 | ++----------------+-----------------------------+ | [7.1.0-7.2.0] | 3.0.15_rev4 and 3.0.15_rev7 | +----------------+-----------------------------+ | [4.0.0-7.0.0] | 3.0.15_rev4 | @@ -358,15 +371,21 @@ The :ref:`NemaGFX C module ` targets the CP The following table describes the version compatibility between the MicroEJ UI Packs and the C modules: -+-----------------+----------------+---------------------------+ -| UI Pack Range | C module Range | Comment | -+=================+================+===========================+ -| 14.0.0 | 2.0.0 | buffer refresh strategies | -+-----------------+----------------+---------------------------+ -| [13.7.0-13.7.2] | [1.1.0-1.2.0] | free image resources | -+-----------------+----------------+---------------------------+ -| [13.5.0-13.6.2] | 1.0.0 | | -+-----------------+----------------+---------------------------+ ++-----------------+---------+------------------+------------------------------+ +| UI Pack | NemaGFX | MicroUI C Module | Comment | ++=================+=========+==================+==============================+ +| [14.0.1-14.0.2] | 3.0.0 | 4.1.0 | VG Pack extensibility | ++-----------------+---------+------------------+------------------------------+ +| [14.0.1-14.0.2] | 2.0.1 | 4.0.1 | C modules harmonization | ++-----------------+---------+------------------+------------------------------+ +| 14.0.0 | 2.0.0 | 4.0.0 | Buffer refresh strategies | ++-----------------+---------+------------------+------------------------------+ +| 13.7.2 | 1.2.0 | [3.1.0-3.1.1] | Update of configuration file | ++-----------------+---------+------------------+------------------------------+ +| 13.7.0 | 1.1.0 | [3.1.0-3.1.1] | Free image resources | ++-----------------+---------+------------------+------------------------------+ +| [13.5.1-13.6.2] | 1.0.0 | | | ++-----------------+---------+------------------+------------------------------+ .. | Copyright 2021-2024, MicroEJ Corp. Content in this space is free diff --git a/VEEPortingGuide/uiReplaces.rst b/VEEPortingGuide/uiReplaces.rst index cc808f1b7..baa0fa8d1 100644 --- a/VEEPortingGuide/uiReplaces.rst +++ b/VEEPortingGuide/uiReplaces.rst @@ -1,8 +1,11 @@ -.. |UIPACKVERSION| replace:: 14.0.0 - -.. |VGPACKVERSION| replace:: 1.5.0 +.. |UIPACKVERSION| replace:: 14.0.2 +.. |VGPACKVERSION| replace:: 1.6.0 +.. |VGAPIVERSION| replace:: 1.6.0 + +.. _C Module MicroUI 4.1.0: https://repository.microej.com/modules/com/microej/clibrary/llimpl/microui/4.1.0/ +.. _C Module MicroUI 4.0.1: https://repository.microej.com/modules/com/microej/clibrary/llimpl/microui/4.0.1/ .. _C Module MicroUI 4.0.0: https://repository.microej.com/modules/com/microej/clibrary/llimpl/microui/4.0.0/ .. _C Module MicroUI 3.1.1: https://repository.microej.com/modules/com/microej/clibrary/llimpl/microui/3.1.1/ .. _C Module MicroUI 3.0.0: https://repository.microej.com/modules/com/microej/clibrary/llimpl/microui/3.0.0/ @@ -12,6 +15,8 @@ .. _C Module MicroUI 1.1.0: https://repository.microej.com/modules/com/microej/clibrary/llimpl/microui/1.1.0/ .. _C Module MicroUI 1.0.3: https://repository.microej.com/modules/com/microej/clibrary/llimpl/microui/1.0.3/ +.. _C Module MicroUI over DMA2D to version 6.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-dma2d/6.0.0/ +.. _C Module DMA2D 5.0.1: https://repository.microej.com/modules/com/microej/clibrary/llimpl/display-dma2d/5.0.1/ .. _C Module DMA2D 5.0.0: https://repository.microej.com/modules/com/microej/clibrary/llimpl/display-dma2d/5.0.0/ .. _C Module DMA2D 4.1.0: https://repository.microej.com/modules/com/microej/clibrary/llimpl/display-dma2d/4.1.0/ .. _C Module DMA2D 4.0.0: https://repository.microej.com/modules/com/microej/clibrary/llimpl/display-dma2d/4.0.0/ @@ -23,6 +28,8 @@ .. _C Module DMA2D 1.0.8: https://repository.microej.com/modules/com/microej/clibrary/llimpl/display-dma2d/1.0.8/ .. _C Module DMA2D 1.0.6: https://repository.microej.com/modules/com/microej/clibrary/llimpl/display-dma2d/1.0.6/ +.. _C Module MicroUI over VGLite to version 9.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-vglite/9.0.0/ +.. _C Module VGLite 8.0.1: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-vglite/8.0.1/ .. _C Module VGLite 8.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-vglite/8.0.0/ .. _C Module VGLite 7.2.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-vglite/7.2.0/ .. _C Module VGLite 7.1.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-vglite/7.1.0/ @@ -33,6 +40,8 @@ .. _C Module VGLite 4.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-vglite/4.0.0/ .. _C Module VGLite 3.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-vglite/3.0.0/ +.. _C Module MicroUI over NemaGFX to version 3.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-nemagfx/3.0.0/ +.. _C Module NemaGFX 2.0.1: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-nemagfx/2.0.1/ .. _C Module NemaGFX 2.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-nemagfx/2.0.0/ .. _C Module NemaGFX 1.2.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-nemagfx/1.2.0/ .. _C Module NemaGFX 1.1.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-nemagfx/1.1.0/ @@ -41,9 +50,13 @@ .. _C Module RT500 7.0.0: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microui-mimxrt595-evk/7.0.0 .. _NXP i.MX RT500: https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/i-mx-rt-crossover-mcus/i-mx-rt500-crossover-mcu-with-arm-cortex-m33-dsp-and-gpu-cores:i.MX-RT500 +.. _VG Pack 1.6.0: https://repository.microej.com/modules/com/microej/pack/vg/vg-pack/1.6.0/ + +.. _C Module MicroVG over VGLite 8.0.1: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/microej/clibrary/llimpl/microvg-vglite/8.0.1/ + .. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/ui_vg_releases_notes_cco.xlsx b/VEEPortingGuide/ui_vg_releases_notes_cco.xlsx new file mode 100644 index 000000000..6d7d1ac1e Binary files /dev/null and b/VEEPortingGuide/ui_vg_releases_notes_cco.xlsx differ diff --git a/VEEPortingGuide/veePortQualification.rst b/VEEPortingGuide/veePortQualification.rst index 2e323844a..192632c5c 100644 --- a/VEEPortingGuide/veePortQualification.rst +++ b/VEEPortingGuide/veePortQualification.rst @@ -70,8 +70,8 @@ The VEE Port Qualification Tools provide the following components: - Used to validate the Low Level APIs implementations. - Validated during the BSP development and whenever an Abstraction Layer implementation is added or changed (see - :ref:`vee_port_testsuite` or check the tutorial - :ref:`tutorial_run_test_suite_on_device`). + :ref:`vee_port_testsuite` or check the section + :ref:`run_test_suite_on_device`). Please refer to the `VEE Port Qualification Tools README `__ for more @@ -302,10 +302,17 @@ Create the Test Suite Runner Project .. note:: ``{PROJECT_LOC}`` refers here to the location of your Test Suite runner project. -Configure and Run the Test Suite -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _run_test_suite_on_device: -Follow the :ref:`tutorial_run_test_suite_on_device` tutorial to configure your VEE Port and run the Test Suite on your Device. +Run a Test Suite on Device +========================== + +Follow the :ref:`run_fs_test_suite_on_esp32_wrover` guide to configure your VEE Port and run the Test Suite on your Device. + +.. toctree:: + :hidden: + + runFsTestSuiteOnESP32WROVER .. _test_suite_versioning: @@ -436,6 +443,13 @@ NET Pack - `4.1.1 `__ - `4.0.2 `__ - `1.3.1 `__ + * - 11.1.0 + - `1.1.4 `__ + - `2.2.3 `__ + - `1.4.2 `__ + - `4.1.1 `__ + - `4.0.2 `__ + - `1.7.0 `__ .. _test_suite_versioning_event_queue: diff --git a/VEEPortingGuide/vg.rst b/VEEPortingGuide/vg.rst index 7b504bf53..ce9264765 100644 --- a/VEEPortingGuide/vg.rst +++ b/VEEPortingGuide/vg.rst @@ -4,12 +4,6 @@ Vector Graphics =============== -.. note:: - - This chapter describes the VG Pack implementation. - The current VG Pack only targets the i.MX RT595 MCU (it is part of the `NXP i.MX RT500 `_ crossover MCU product line that embeds the Vivante GCNanoLiteV IP from Verisilicon). - Please contact our support team for other hardware accelerators (GPU with vector graphics acceleration). - .. toctree:: :maxdepth: 2 diff --git a/VEEPortingGuide/vgCco.rst b/VEEPortingGuide/vgCco.rst index 08b2854d4..729cb8f86 100644 --- a/VEEPortingGuide/vgCco.rst +++ b/VEEPortingGuide/vgCco.rst @@ -9,14 +9,14 @@ Principle Several C modules implement the VG Pack's Abstraction Layer APIs. Some are generic, and some are VEE Port dependent (more precisely: GPU dependent). -The generic modules provide header files to be extended by the specific modules. +The generic modules provide header files to be extended by the specific modules. The generic C modules are available on the :ref:`central_repository` and the specific C modules on the :ref:`developer_repository`. The following picture illustrates the available C modules and their relations for an implementation that uses: * FreeType library for the font renderer and the font layouter in simple layout mode. * Harfbuzz library for the font layouter in complex layout mode. -* Vivante VGLite library for the drawing of vector paths +* *GPU* library symbolizes the library for the drawing of vector paths over a GPU. The following chapters explain the aim and relations of each C module. @@ -35,14 +35,6 @@ UI Pack & MicroUI C Modules The UI Pack provides a header file to implement the MicroUI drawings: ``LLUI_PAINTER_impl.h``. See :ref:`section_ui_cco` chapter to have more information. -Library: Vivante VGLite -======================= - -This library is the official Vivante VGLite library. -The C modules use its header files to target the GPU. - -.. note:: The library must be patched to be compatible with the C module "MicroUI over VGLite". Consult the C module's ReadMe file for more information. - VG Pack ======= @@ -65,11 +57,11 @@ C Module: MicroVG Description ----------- -This generic C module provides an implementation of MicroVG concepts: matrix, path, linear gradient and font; respectively ``LLVG_MATRIX_impl.c``, ``LLVG_PATH_impl.c``, ``LLVG_GRADIENT_impl.c`` and ``LLVG_FONT_freetype.c``. +This generic C module provides an implementation of MicroVG concepts: matrix, path, gradient and font; respectively ``LLVG_MATRIX_impl.c``, ``LLVG_PATH_impl_single.c``/``LLVG_PATH_impl_dual.c``, ``LLVG_GRADIENT_impl_stub.c`` and ``LLVG_FONT_impl_freetype.c``. * Matrix (see Matrix module's :ref:`section_vg_matrix_llapi`): a basic software implementation. -* Path (see Path module's :ref:`section_vg_path_llapi`): a generic implementation that manages the command buffer's life cycle and dispatches the command encoding to a 3rd-party header file ``microvg_path.h``. -* Gradient (see Gradient module's :ref:`section_vg_gradient_llapi`): a generic implementation that manages the gradient buffer's life cycle and dispatches the gradient encoding to a 3rd-party header file ``microvg_gradient.h``. +* Path (see Path module's :ref:`section_vg_path_llapi`): a generic implementation that manages the command buffer's life cycle and dispatches the command encoding to a 3rd-party header file ``vg_path.h``. +* Gradient (see Gradient module's :ref:`section_vg_gradient_llapi`): a generic minimal implementation that only handles a single color (resulting in filling paths with a solid color). To fully handle linear gradients, the API from ``LLVG_GRADIENT_impl.h`` must be implemented. * Font (see Font module's :ref:`section_vg_font_llapi`): an implementation of vector font over FreeType: open font file and retrieve font's characteristics. * The MicroVG painter native functions are implemented in ``LLVG_PAINTER_impl.c`` and the drawings are redirected to ``vg_drawing.h``. * Image management is too specific to the GPU and is not implemented in this C module. @@ -91,7 +83,7 @@ Usage 1. This C module transitively fetches the :ref:`C Module for MicroUI`, follow its implementation rules. 2. Add all C files in the BSP project. -3. Configure the option in the header file ``microvg_configuration.h``. +3. Configure the options in the header file ``vg_configuration.h``. .. _section_vg_c_module_freetype: @@ -111,12 +103,12 @@ Memory Heap Configuration ------------------------- The FreeType library requires a memory Heap for FreeType internal objects allocated when a font file is loaded (see https://freetype.org/freetype2/docs/design/design-4.html). -The size of this heap depends on the number of fonts loaded in parallel and on the fonts themselves. -This size is defined by ``VG_FEATURE_FREETYPE_HEAP_SIZE`` in ``microvg_configuration.h``. +The size of this heap depends on the number of fonts loaded in parallel and on the fonts themselves. +This size is defined by ``VG_FEATURE_FREETYPE_HEAP_SIZE`` in ``vg_configuration.h``. All fonts do not require the same heap size. FreeType heap usage can be monitored using the following configurations: -* ``MICROVG_MONITOR_HEAP`` defined in ``microvg_helper.h`` +* ``MICROVG_MONITOR_HEAP`` defined in ``vg_helper.h`` * ``MEJ_LOG_MICROVG`` and ``MEJ_LOG_INFO_LEVEL`` defined in ``mej_log.h`` Principle @@ -155,11 +147,11 @@ The library Harfbuzz compatible with MicroEJ is packaged in a C module on the :r This C module provides a fork of Harfbuzz 4.2.1. -The Harfbuzz library requires a memory Heap for Harfbuzz internal objects allocated when a font file is loaded. -The size of this heap depends on the number of fonts loaded in parallel and on the fonts themselves. -This size is defined by ``VG_FEATURE_HARFBUZZ_HEAP_SIZE_HEAP`` in ``microvg_configuration.h``. +The Harfbuzz library requires a memory Heap for Harfbuzz internal objects allocated when a font file is loaded. +The size of this heap depends on the number of fonts loaded in parallel and on the fonts themselves. +This size is defined by ``VG_FEATURE_HARFBUZZ_HEAP_SIZE_HEAP`` in ``vg_configuration.h``. -All fonts do not require the same heap size. The ``MICROVG_MONITOR_HEAP`` define in ``microvg_helper.h`` and ``MEJ_LOG_MICROVG`` and ``MEJ_LOG_INFO_LEVEL`` defines in ``mej_log.h`` can be used to monitor the Harfbuzz heap evolution. +All fonts do not require the same heap size. The ``MICROVG_MONITOR_HEAP`` define in ``vg_helper.h`` and ``MEJ_LOG_MICROVG`` and ``MEJ_LOG_INFO_LEVEL`` defines in ``mej_log.h`` can be used to monitor the Harfbuzz heap evolution. FreeType and Harfbuzz libraries are not sharing the same heap, but this could easilly be done by updating ``ft_system.c`` and ``hb-alloc.c`` files. @@ -173,8 +165,11 @@ Overview This C module is a specific implementation of the VG Pack drawings over the official Vivante VGLite library (that targets some GPU with vector graphics acceleration): -* It implements the MicroVG API ``vg_drawing.h`` in ``vg_drawing_vglite.c`` and ``LLVG_PAINTER_FONT_freetype_vglite.c``. -* It implements the MicroVG Image management (draw a compile-time image, create a BufferedVectorImage, etc.): ``LLVG_RAW_impl.c``. +* It implements the MicroVG API ``LLVG_impl.h`` in ``LLVG_impl_vglite.c``. +* It implements the MicroVG API ``LLVG_GRADIENT_impl.h`` in ``LLVG_GRADIENT_impl_vglite.c``. +* It implements the MicroVG API ``vg_drawing.h`` in ``vg_drawing_vglite.c``. +* It implements the MicroVG API ``vg_path.h`` in ``vg_path_vglite.c``. +* It implements the MicroVG Image management (draw a compile-time image, create a BufferedVectorImage, etc.) in ``vg_drawing_vglite_image.c``. * It provides an implementation of MicroVG drawings to the MicroVG BufferedVectorImage: ``vg_drawing_bvi.c``. * It also implements MicroUI drawings to the MicroVG BufferedVectorImage: ``ui_drawing_bvi.c``. @@ -187,6 +182,8 @@ The implementation requires: This C module is available on the :ref:`developer_repository`: `com.microej.clibrary.llimpl#microvg-vglite`_. +.. warning:: The library must be patched to be compatible with the C module "MicroUI over VGLite". Consult the C module's ReadMe file for more information. + Usage ----- @@ -195,6 +192,39 @@ Usage .. _com.microej.clibrary.llimpl#microvg-vglite: https://forge.microej.com/artifactory/microej-developer-repository-release/com/microej/clibrary/llimpl/microvg-vglite/ + +.. _section_vg_c_module_microvg_nema: + +C Module: MicroVG Over NemaVG +============================= + +Overview +-------- + +This C module is a specific implementation of the VG Pack drawings over the official Think Silicon Nema VG library (that targets some GPU with vector graphics acceleration): + +* It implements the MicroVG API ``vg_drawing.h`` in ``vg_drawing_nema.c``. +* It implements the MicroVG Image management (draw a compile-time image, create a BufferedVectorImage, etc.): ``vg_drawing_nema_image.c``. +* It provides an implementation of MicroVG drawings to the MicroVG BufferedVectorImage: ``vg_drawing_bvi.c``. +* It also implements MicroUI drawings to the MicroVG BufferedVectorImage: ``ui_drawing_bvi.c``. + +The implementation requires: + +* the concepts of the C module MicroVG, +* the concepts of the C module MicroUI over NemaVG, +* the FreeType library, +* the Think Silicon NemaVG library. + +This C module is available on the :ref:`developer_repository`: `com.microej.clibrary.llimpl#microvg-nema`_. + +Usage +----- + +1. This C module transitively fetches the :ref:`C Module for MicroUI for NemaGFX`, follow its implementation rules. +2. Add all C files in the BSP project. + +.. _com.microej.clibrary.llimpl#microvg-nema: https://forge.microej.com/ui/native/microej-developer-repository-release/com/microej/clibrary/llimpl/microvg-nemavg/ + Compatibility ============= @@ -205,8 +235,8 @@ The compatibility between the components (Packs, C modules, and Libraries) is de .. _ej.microvg.VectorFont.close(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/microvg/VectorFont.html#close-- .. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/vgChangeLog.rst b/VEEPortingGuide/vgChangeLog.rst index c260973b8..323b5ec62 100644 --- a/VEEPortingGuide/vgChangeLog.rst +++ b/VEEPortingGuide/vgChangeLog.rst @@ -4,6 +4,70 @@ Changelog ========= +[1.6.0] - 2024-07-19 +==================== + +MicroVG Implementation +"""""""""""""""""""""" + +**Added** + +* Allow the ``nema`` value for the MicroVG implementation (see :ref:`section_microvg_installation`). + +**Changed** + +* Compatible with UI Pack 14.0.1. + +Front Panel +""""""""""" + +**Added** + +* Support ``nema`` image format and limitations (blend modes ``SCREEN`` and ``MULTIPLY`` are not supported). + +LLAPIs +"""""" + +**Added** + +* Add the LLAPI ``LLVG_MATRIX_IMPL_transformPoint``. +* Add the new type ``MICROVG_Image``. + +**Changed** + +* Change the semantic of the LLAPI ``LLVG_GRADIENT_IMPL_initializeGradient``: the positions array cannot be ``NULL``. +* Add ``const`` modifiers for parameters of the following functions: + + * ``LLVG_GRADIENT_IMPL_initializeGradient``, + * ``LLVG_MATRIX_IMPL_copy``, + * ``LLVG_MATRIX_IMPL_multiply``, + * ``LLVG_MATRIX_IMPL_setConcat``, + * ``LLVG_MATRIX_IMPL_concatenate``, + * ``LLVG_MATRIX_IMPL_postConcat``. + +* Use the new type ``MICROVG_Image`` in the signature of the following functions: + + * ``LLVG_BVI_IMPL_map_context``, + * ``LLVG_PAINTER_IMPL_drawImage``. + +[1.5.1] - 2024-04-11 +==================== + +Front Panel +""""""""""" + +**Fixed** + +* Fix the drawing of a BufferedVectorImage in a BufferedVectorImage with a clip. +* Fix the drawing of a glyph with path overlap. + +C Module VGLite +""""""""""""""" + +**Fixed** + +* Fix the drawing of a VG RAW image in a BufferedVectorImage with a clip. + [1.5.0] - 2024-02-15 ==================== @@ -96,7 +160,7 @@ C Module VGLite **Fixed** * Fix some comments. -* Fix the dynamic path drawing on i.MX RT1170 Evaluation Kit (use the same quality of paths as vector images). +* Fix the dynamic path drawing on i.MX RT1170 Evaluation Kit (use the same quality of paths as vector images). * Fix the path drawing on i.MX RT1170 Evaluation Kit (disable the color pre-multiplication). * Fix the rendering of some blending modes on i.MX RT1170 Evaluation Kit by disabling the GPU pre-multiplication when required. @@ -108,7 +172,7 @@ MicroVG **Fixed** -* Fix the path command "move relative". +* Fix the path command "move relative". C Module VGLite """"""""""""""" @@ -218,7 +282,7 @@ C Module MicroVG **Removed** * Remove the useless implementation of `LLVG_PATH_IMPL_mergePaths` (useless since VG Pack 1.2). -* Remove partial Freetype implementation that manipulates the font's glyphs as bitmaps (not compatible anymore with VG pack 1.3.0). +* Remove partial Freetype implementation that manipulates the font's glyphs as bitmaps (not compatible anymore with VG pack 1.3.0). C Module VGLite """"""""""""""" @@ -272,8 +336,8 @@ MicroVG **Changed** * Compatible with `MicroVG API 1.2`_. -* Change the VectorImage internal format: *raw* format instead of *immutables* format. - +* Change the VectorImage internal format: *raw* format instead of *immutables* format. + .. _MicroVG API 1.2: https://repository.microej.com/modules/ej/api/microvg/1.2.0/ Front Panel @@ -281,7 +345,7 @@ Front Panel **Fixed** -* Fix the redirection of fillEllipseArc to the right software algorithm. +* Fix the redirection of fillEllipseArc to the right software algorithm. Vector Image Converter """""""""""""""""""""" @@ -295,12 +359,12 @@ C Module MicroVG **Added** -* Add ``LLVG_MATRIX_IMPL_multiply(c,a,b)`` (C = AxB): faster than ``setConcat`` when destination and source target the same matrix. +* Add ``LLVG_MATRIX_IMPL_multiply(c,a,b)`` (C = AxB): faster than ``setConcat`` when destination and source target the same matrix. * Add an entry point to initialize the path engine on startup. **Changed** -* Prevent a copy in a temp matrix when calling ``postXXX`` functions. +* Prevent a copy in a temp matrix when calling ``postXXX`` functions. **Fixed** @@ -319,12 +383,12 @@ C Module VGLite * Reduce the gradient footprint in ``BufferedVectorImage``. * Harmonize the use of ``vg_drawer.h`` functions (instead of ``VG_DRAWER_drawer_t`` functions) in ``BufferedVectorImage``. -* Use the global fields *VGLite paths* instead of functions fields (prevent dynamic allocation on task stack). +* Use the global fields *VGLite paths* instead of functions fields (prevent dynamic allocation on task stack). **Fixed** -* Fix the drawing of a text in a ``BufferedVectorImage``: do not wake-up the GPU. -* Fix the constants used in ``get_command_parameter_number()`` function (no side-effect). +* Fix the drawing of a text in a ``BufferedVectorImage``: do not wake-up the GPU. +* Fix the constants used in ``get_command_parameter_number()`` function (no side-effect). [1.1.1] - 2022-09-05 ==================== @@ -343,7 +407,7 @@ MicroVG * Compatible with `MicroVG API 1.1`_. * Change color animation interpolation (match Android formula). - + **Fixed** * Fix NullPointerException while sorting TranslateXY VectorDrawableObjectAnimator in vectorimage-converter. @@ -352,12 +416,12 @@ MicroVG LLAPIs """""" - + **Added** * Add LLAPI to close a font: ``LLVG_FONT_IMPL_dispose()``. -**Changed** +**Changed** * Manage the font :ref:`complex layout `. * Returns an error code when drawing something. @@ -367,8 +431,8 @@ C Module MicroVG **Added** -* Add ``microvg_configuration.h`` versionning. -* Add an option to load a VectorFont from the external resources. +* Add ``microvg_configuration.h`` versioning. +* Add an option to load a VectorFont from the external resources. * Add an option to select the text layouter between FreeType and Harfbuzz. * Add a function to apply an opacity on a color. * Add the text layout. @@ -383,16 +447,16 @@ C Module VGLite **Added** * Add the ``BufferedVectorImage`` feature (BVI). - + **Changed** * Manage the closed fonts. * Move ``ftvglite.c`` and ``ftvglite.h`` to C Module FreeType. -* Extract text layout to C Module MicroVG. +* Extract text layout to C Module MicroVG. * Get fill rule configuration from each glyph ``FT_Outline->flags`` instead of defaulting it to ``VG_LITE_FILL_EVEN_ODD``. * Use the MicroUI over VGLite's Vectorial Drawer mechanism. * Join character bboxes at baseline for ``drawStringOnCircle``. - + [1.0.1] - 2022-05-16 ==================== @@ -419,8 +483,8 @@ MicroVG * Compatible with MicroVG API 1.0.0. .. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/vgFont.rst b/VEEPortingGuide/vgFont.rst index 378aea97b..e1b2cb840 100644 --- a/VEEPortingGuide/vgFont.rst +++ b/VEEPortingGuide/vgFont.rst @@ -52,10 +52,9 @@ There are two separate Abstraction Layer API header files (see :ref:`LLVG-FONT-A Font Abstraction Layer API * MicroVG library calls the BSP functions through the header files ``LLVG_FONT_impl.h`` and ``LLVG_PAINTER_impl.h``. -* The :ref:`C module MicroVG ` provides a default implementation of ``LLVG_FONT_impl.h`` over FreeType. -* This C module also provides an implementation of ``LLVG_PAINTER_impl.c`` that synchronizes the drawing with the MicroUI Graphics Engine and redirects the drawing itself to a third-party drawer. -* A C module dedicated to a GPU provides an implementation of this drawer. It also redirects the :ref:`complex layout ` to a third party C module. -* The drawer also manages the :ref:`section_vg_gradient`. +* The :ref:`C module MicroVG ` provides a default implementation of ``LLVG_FONT_impl.h`` over FreeType. It also redirects the :ref:`complex layout ` to a third party C module. +* This C module also provides an implementation of ``LLVG_PAINTER_impl.c`` that synchronizes the drawing with the MicroUI Graphics Engine and redirects the drawing itself to a third-party drawer through ``vg_drawing.h``. +* A C module dedicated to a GPU provides an implementation of this drawer (``vg_drawing_gpu.c``) that implements the drawings over the GPU library. * The :ref:`C module Harfbuzz ` provides an implementation of :ref:`complex layout `. * These files are automatically copied in the BSP project when fetching the C modules during the VEE Port build. diff --git a/VEEPortingGuide/vgGradient.rst b/VEEPortingGuide/vgGradient.rst index 70542b39c..8d2a3af2c 100644 --- a/VEEPortingGuide/vgGradient.rst +++ b/VEEPortingGuide/vgGradient.rst @@ -15,8 +15,8 @@ This module is composed of only one element: an implementation of the Abstractio Functional Description ====================== -The Gradient module implements the framework of the MicroVG `LinearGradient`_. -It provides Abstraction Layer APIs that consist in creating a linear gradient in a VEE Port-specific format. +The Gradient module implements the framework of the MicroVG `LinearGradient`_. +It provides Abstraction Layer APIs that consist in creating a linear gradient in a VEE Port-specific format. After the gradient creation and encoding, the gradient data should not change when the application draws it: the encoded format should be used by the VEE Port-specific implementation (generally GPU). A linear gradient is a succession of colors at different positions. @@ -45,10 +45,11 @@ There are two separate Abstraction Layer API header files (see :ref:`LLVG-GRADIE Gradient Abstraction Layer API + * MicroVG library calls the BSP functions through the header files ``LLVG_GRADIENT_impl.h`` and ``LLVG_PAINTER_impl.h``. -* The :ref:`C module MicroVG ` provides a default implementation of ``LLVG_GRADIENT_impl.h``: it manages the gradient buffer creation and filling, then redirect the gradient encoding to ``microvg_gradient.h``. -* This C module also provides an implementation of ``LLVG_PAINTER_impl.c`` that synchronizes the drawing with the MicroUI Graphics Engine and redirects the drawing itself to a third-party drawer. -* A C module dedicated to a GPU provides an implementation of ``LLVG_PAINTER_impl.h`` and ``microvg_gradient.h``: it encodes the gradient and implements the drawings over the GPU library. +* The :ref:`C module MicroVG ` provides an implementation of ``LLVG_PAINTER_impl.c`` that synchronizes the drawing with the MicroUI Graphics Engine and redirects the drawing itself to a third-party drawer through ``vg_drawing.h``.. +* A C module dedicated to a GPU provides an implementation of this drawer (``vg_drawing_gpu.c``) that implements the drawings over the GPU library. +* This dedicated GPU C module provides an implementation of ``LLVG_GRADIENT_impl.h`` (``LLVG_GRADIENT_impl_gpu.c``) that encodes the gradient. * These files are automatically copied in the BSP project when fetching the C modules during the VEE Port build. .. _VectorGraphicsPainter: https://repository.microej.com/javadoc/microej_5.x/apis/ej/microvg/VectorGraphicsPainter.html @@ -59,8 +60,8 @@ Use The MicroVG Gradient APIs are available in the class ``ej.microvg.`` `LinearGradient`_. .. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/vgImage.rst b/VEEPortingGuide/vgImage.rst index eef1fd4c2..a441d3783 100644 --- a/VEEPortingGuide/vgImage.rst +++ b/VEEPortingGuide/vgImage.rst @@ -17,6 +17,9 @@ This module is composed of several elements: Compile-time Image ================== +Overview +-------- + The Image module implements the MicroVG `VectorImage`_ framework. It provides an offline tool that consists in opening and decoding an image file and some Abstraction Layer APIs that manipulate the image at runtime. @@ -36,7 +39,7 @@ Image Generator The offline tool is an extension of the MicroUI :ref:`section_image_generator`. This tool is automatically installed during the VEE Port build. -The tool converts : +The tool converts: * The Android Vector Drawable (AVD): this kind of image can hold linear gradients, animations on colors, opacity, path transformations, etc. * The Scalable Vector Graphics (SVG): this kind of image is partially supported: linear gradients but no animations. It is advised to convert the SVG files into AVD files before using the Image Converter tool. @@ -59,6 +62,68 @@ This is an example of a ``vectorimage.list`` file: # Convert an SVG in signed 8-bit format /svg_image.svg:VG8 +The image generator must be extended to encode the binary data in a format compatible with the GPU. + +Default Extensions +------------------ + +The image generator provides some implementations that targets different GPUs: + +* ``NemaImageGenerator``: generates binary files compatible with the :ref:`section_vg_c_module_microvg_nema`. +* ``VgliteImageGenerator``: generates binary files compatible with the :ref:`section_vg_c_module_microvg_vglite`. + +Refer to the chapter :ref:`section_microvg_installation` for more information about the image generator configuration or to the next chapter to target another GPU. + +.. _section_vg_image_generator_extension: + +Custom Extension +---------------- + +The Image Generator can be extended to target a new GPU. +This extension follows the same rules than the :ref:`MicroUI Image Generator extension`. + +1. Create a ``std-javalib`` project. The module name must start with the prefix ``imageGenerator`` (for instance ``imageGeneratorMyGPU``). +2. Add the dependency: + + .. code-block:: xml + + + + + + Where ``x.y.z`` is the VG Pack version used to build the VEE Port (minimum ``1.6.0``). The ``module.ivy`` should look like: + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + +3. Implements the interface ``ej.microvg.image.ImageGenerator``; the name of the class must be ``ej.microvg.image.[Prefix]ImageGenerator`` where ``[Prefix]`` is the name that will be set in the VEE Port configuration file (see :ref:`section_microvg_installation`). +4. Build the project. +5. Copy the generated jar: ``target~/artifacts/imageGeneratorMyGPU.jar`` in the VEE Port configuration project folder: ``MyVEEPort-configuration/dropins/tools/`` +6. Rebuild the VEE Port. + MicroVG Library --------------- @@ -148,7 +213,7 @@ The way to register the drawing commands is strongly linked to the targeted GPU: As a consequence, the implementation is dedicated to the GPU. The :ref:`section_vg_cco` provide some implementations, and the Front Panel (for the Simulation) features the same limitations as the embedded side (it is not possible to store a MicroUI drawing in the simulator if the embedded side is not able to perform it). -.. [#note_uibvi] The compatible MicroUI drawings depend on the GPU Port; see:ref:`section_vg_cco`. +.. [#note_uibvi] The compatible MicroUI drawings depend on the GPU Port; see :ref:`section_vg_cco`. Runtime Image ============= @@ -202,7 +267,9 @@ There are two separate Abstraction Layer API header files: Image Abstraction Layer API * MicroVG library calls the BSP functions through the header files ``LLVG_BVI_impl.h`` and ``LLVG_PAINTER_impl.h``. -* A C module dedicated to a GPU provides an implementation of ``LLVG_BVI_impl.h`` and ``LLVG_PATH_PAINTER_impl.h``: the implementation is specific to the target (the GPU): the format of the RAW paths, gradients, and animations are GPU compliant. +* The :ref:`C module MicroVG ` an implementation of ``LLVG_PAINTER_impl.c`` that synchronizes the drawing with the MicroUI Graphics Engine and redirects the drawing itself to a third-party drawer through ``vg_drawing.h``. +* A C module dedicated to a GPU provides an implementation of this drawer (``vg_drawing_gpu.c``) that implements the drawings over the GPU library. +* This dedicated GPU C module provides an implementation of ``LLVG_BVI_impl.h`` (``LLVG_BVI_impl_gpu.c``): the implementation is specific to the target (the GPU): the format of the RAW paths, gradients, and animations are GPU compliant. * These files are automatically copied in the BSP project when fetching the C modules during the VEE Port build. Simulation diff --git a/VEEPortingGuide/vgLowLevel.rst b/VEEPortingGuide/vgLowLevel.rst index 8fa71f10e..913decf52 100644 --- a/VEEPortingGuide/vgLowLevel.rst +++ b/VEEPortingGuide/vgLowLevel.rst @@ -7,7 +7,7 @@ Abstraction Layer API Principle ========= -The MicroVG implementation for MicroEJ requires an Abstraction Layer implementation. +The MicroVG implementation for MicroEJ requires an Abstraction Layer implementation. The Abstraction Layer implementation consists of a set of header files to implement in C to target the hardware drivers. The VG Pack's embedded Front Panel extension implements all MicroVG features for the simulator. @@ -41,13 +41,13 @@ Simulator MicroVG Simulator Abstraction Layer API -The Simulator's five VG engines are grouped in a :ref:`Front Panel extension `. +The Simulator's five VG engines are grouped in a :ref:`Front Panel extension `. -.. note:: The current implementation is built-in in the VG Pack and is only compatible with the i.MX RT595 MCU (see :ref:`VG Pack note`). +This engine provides the compatibility with Vivante VGLite and Think Silicon Nema VG GPUs and it can be extended to fit another GPU. .. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/vgMicrovg.rst b/VEEPortingGuide/vgMicrovg.rst index 8c97eba08..80c4fe45f 100644 --- a/VEEPortingGuide/vgMicrovg.rst +++ b/VEEPortingGuide/vgMicrovg.rst @@ -42,12 +42,29 @@ In the VEE Port configuration's :ref:`module description file -.. note:: The latest current pack version is |VGPACKVERSION|. +.. note:: The latest current Pack version is |VGPACKVERSION|. The VG Pack will be automatically available after a VEE Port rebuild. .. _MicroVG library: https://repository.microej.com/modules/com/microej/pack/vg/vg-pack/ +The properties file ``microvg/microvg.properties`` is required to configure the VG Pack. +More specifically, it allows to configure the :ref:`section_vg_image_generator` and the front panel to fit a specific GPU. +This properties file must contain a property named ``implementation``. +Two values are currently available: + +* ``nema``: to be compatible with the :ref:`Think Silicon Nema VG` GPU. +* ``vglite``: to be compatible with the :ref:`Vivante VGLite` GPU. + +Example: + +.. code-block:: XML + + implementation=nema + +A custom extension can be used to target another GPU. +The name of the property ``implementation`` is used to identify the :ref:`section_vg_image_generator_extension` and the :ref:`Front Panel Extension`. + Use === diff --git a/VEEPortingGuide/vgMigrationGuide.rst b/VEEPortingGuide/vgMigrationGuide.rst index 4b14bcc7e..64a907e13 100644 --- a/VEEPortingGuide/vgMigrationGuide.rst +++ b/VEEPortingGuide/vgMigrationGuide.rst @@ -1,3 +1,4 @@ +.. include:: uiReplaces.rst .. _section_vg_migrationguide: @@ -5,7 +6,78 @@ Migration Guide =============== -From 1.4.x to 1.5.0 +From 1.5.x to 1.6.0 +=================== + +VEE Port Configuration project +"""""""""""""""""""""""""""""" + +* Update the UI Pack to version 14.0.1 or higher. +* Specify the ``implementation`` property, as written in the section :ref:`section_microvg_installation`. + +LLAPIs +"""""" + +* Update your implementation of the following functions to match the signature changes. + + * ``LLVG_GRADIENT_IMPL_initializeGradient``, + * ``LLVG_MATRIX_IMPL_copy``, + * ``LLVG_MATRIX_IMPL_multiply``, + * ``LLVG_MATRIX_IMPL_setConcat``, + * ``LLVG_MATRIX_IMPL_concatenate``, + * ``LLVG_MATRIX_IMPL_postConcat``, + * ``LLVG_BVI_IMPL_map_context``, + * ``LLVG_PAINTER_IMPL_drawImage``. + +BSP with VGLite +""""""""""""""" + +* Follow the migration steps of the :ref:`C Module MicroUI over VGLite `. +* *[VEE Port configuration project]* + + * Fetch the `VG Pack 1.6.0`_ and the `C Module MicroVG over VGLite 8.0.1`_. + +* *[BSP project]* + + * Delete the following file in the ``ui`` directory: + + * ``src/ui_drawing_bvi.c``. + + * Delete the following files in the ``vg`` directory: + + * ``inc/microvg_font_freetype.h``, + * ``inc/microvg_gradient.h``, + * ``inc/microvg_helper.h``, + * ``inc/microvg_path.h``, + * ``inc/microvg_trace.h``, + * ``src/LLVG_BVI_stub.c``, + * ``src/LLVG_FONT_freetype.c``, + * ``src/LLVG_FONT_stub.c``, + * ``src/LLVG_GRADIENT_impl.c``, + * ``src/LLVG_impl.c``, + * ``src/LLVG_PATH_impl.c``, + * ``src/LLVG_PATH_stub.c``, + * ``src/microvg_helper.c``, + + * ``inc/vg_bvi_vglite.h``, + * ``inc/vg_drawing_vglite.h``, + * ``inc/vg_vglite_helper.h``, + * ``src/LLVG_GRADIENT_impl_vglite.c``, + * ``src/LLVG_impl_vglite.c``, + * ``src/vg_drawing_bvi.c``, + * ``src/vg_drawing_vglite_image.c``, + * ``src/vg_drawing_vglite.c``, + * ``src/vg_path_vglite.c``, + * ``src/vg_vglite_helper.c``. + + * Delete the properties files ``cco_microvg.properties`` and ``cco_microvg-vglite.properties``. + * Build the VEE Port. + * Configure the C Module MicroVG in ``vg/inc/vg_configuration.h``, based on your previous settings in ``vg/inc/microvg_configuration.h``. + * Delete ``vg/inc/microvg_configuration.h``. + * Add the source files in ``vg/src`` and ``vg_vglite/src`` to the project. + * Add the path ``vg_vglite/inc`` to the include path. + +From 1.4.x to 1.5.1 =================== VEE Port Configuration Project @@ -19,7 +91,7 @@ BSP with VGLite * Follow the migration steps of :ref:`C Module MicroUI-VGLite 8.0.0 `. * *[VEE Port configuration project]* - * Fetch VG Pack 1.5.0, C Modules MicroVG 5.0.0 and MicroVG-VGLite 7.0.0. + * Fetch VG Pack 1.5.1, C Modules MicroVG 5.0.0 and MicroVG-VGLite 7.0.1. * *[BSP project]* @@ -40,9 +112,9 @@ BSP with VGLite * *[BSP project]* * Delete the properties files ``cco_microvg.properties`` and ``cco_microvg-vglite.properties``. - + * Build the VEE Port, the FreeType library (in case of a dedicated project), and the BSP. - + From 1.2.x to 1.3.0 =================== @@ -66,13 +138,13 @@ BSP with VGLite * Delete the C files ``freetype_bitmap_helper.h``, ``freetype_bitmap_helper.c``, ``LLVG_BVI_impl.c``, ``LLVG_FONT_PAINTER_freetype_bitmap.c`` and ``LLVG_PATH_PAINTER_vglite.c`` and remove them from the C project configuration. * In the C project configuration, include the new C files ``ui_drawing_bvi.c``, ``LLVG_BVI_stub.c``, ``LLVG_PAINTER_impl.c``, ``vg_drawing_bvi.c``, ``vg_drawing_stub.c``, ``vg_drawing_vglite.c`` and ``vg_drawing.c``. * In the C project configuration, set the define ``LLUI_GC_SUPPORTED_FORMATS=2`` to enable the BufferedVectorImage support. - * Verify the options in ``microvg_configuration.h``. - + * Verify the options in ``microvg_configuration.h``. + * Build the VEE Port, the FreeType library (in case of a dedicated project), and the BSP. .. - | Copyright 2021-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification + | Copyright 2021-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/vgPath.rst b/VEEPortingGuide/vgPath.rst index 641e3e60c..ac1c242a7 100644 --- a/VEEPortingGuide/vgPath.rst +++ b/VEEPortingGuide/vgPath.rst @@ -8,7 +8,7 @@ Principle ========= The Path module contains the C part of the MicroVG implementation, which manages vector paths. -This module is composed of two elements: +This module is composed of two elements: * an implementation of Abstraction Layer APIs to create path elements compatible with the hardware, * an implementation of Abstraction Layer APIs for MicroVG drawings. @@ -18,8 +18,8 @@ This module is composed of two elements: Functional Description ====================== -The Path module implements the framework of the MicroVG `Path`_. -It provides Abstraction Layer APIs that create and merge some paths in a VEE Port-specific format. +The Path module implements the framework of the MicroVG `Path`_. +It provides Abstraction Layer APIs that create and merge some paths in a VEE Port-specific format. After the path creation and encoding, the path data should not change when the application draws it: the encoded format should be used by the VEE Port-specific implementation (generally GPU). A path is a succession of commands. @@ -62,10 +62,10 @@ There are two separate Abstraction Layer API header files (see :ref:`LLVG-PATH-A Path Abstraction Layer API * MicroVG library calls the BSP functions through the header files ``LLVG_PATH_impl.h`` and ``LLVG_PAINTER_impl.h``. -* The :ref:`C module MicroVG ` provides a default implementation of ``LLVG_PATH_impl.h``: it manages the path buffer creation and filling, then redirect the command encoding to ``microvg_path.h``. -* This C module also provides an implementation of ``LLVG_PAINTER_impl.c`` that synchronizes the drawing with the MicroUI Graphics Engine and redirects the drawing itself to a third-party drawer. -* A C module dedicated to a GPU provides an implementation of this drawer and ``microvg_path.h``: it encodes the path commands and implements the drawings over the GPU library. -* The drawer also manages the :ref:`section_vg_gradient`. +* The :ref:`C module MicroVG ` provides a default implementation of ``LLVG_PATH_impl.h``: it manages the path buffer creation and filling, then redirect the command encoding to ``vg_path.h``. +* This C module also provides an implementation of ``LLVG_PAINTER_impl.c`` that synchronizes the drawing with the MicroUI Graphics Engine and redirects the drawing itself to a third-party drawer through ``vg_drawing.h``. +* A C module dedicated to a GPU provides an implementation of this drawer (``vg_drawing_gpu.c``) that implements the drawings over the GPU library (it also manages the :ref:`section_vg_gradient`). +* This dedicated GPU C module provides an implementation of ``vg_path.h`` (``vg_path_gpu.c``) that encodes the path commands. * These files are automatically copied in the BSP project when fetching the C modules during the VEE Port build. .. _VectorGraphicsPainter: https://repository.microej.com/javadoc/microej_5.x/apis/ej/microvg/VectorGraphicsPainter.html @@ -76,8 +76,8 @@ Use The MicroVG Path APIs are available in the class ``ej.microvg.`` `Path`_. .. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/vgReleaseNotes.rst b/VEEPortingGuide/vgReleaseNotes.rst index 758afc01c..7fd8c8545 100644 --- a/VEEPortingGuide/vgReleaseNotes.rst +++ b/VEEPortingGuide/vgReleaseNotes.rst @@ -10,12 +10,12 @@ UI Pack Compatibility Version ============================= The current VG Pack version is |VGPACKVERSION|. -The following table describes the compatibility ranges between VG and UI Packs. +The following table describes the compatibility ranges between VG and UI Packs. +---------------+-----------------+----------------------------------+ | VG Pack Range | UI Pack Range | Comment | +===============+=================+==================================+ -| 1.5.0 | 14.0.0 | UI Pack major version | +| [1.5.0-1.6.0] | [14.0.0-15.0.0[ | UI Pack major version | +---------------+-----------------+----------------------------------+ | [1.3.0-1.4.2] | [13.5.0-14.0.0[ | BufferedImage with custom format | +---------------+-----------------+----------------------------------+ @@ -37,7 +37,7 @@ The following table describes Foundation Libraries API versions implemented in M * - VG Pack Range - MicroVG - * - [1.4.0-1.5.0] + * - [1.4.0-1.6.0] - `1.4.0 `_ * - 1.3.0 - `1.3.0 `_ @@ -54,37 +54,71 @@ C Modules Compatibility Version The C modules are described :ref:`here `. Several generic C modules are available for a given version of the VG Pack. -In addition to generic C modules, the specific implementation of the VG Pack over Vivante VGLite depends on: +In addition to generic C modules, the specific implementations of the VG Pack over Vivante VGLite and Think Silicon NemaVG extend the main MicroVG C module. +They override the default implementation to use a GPU to perform the drawings. +Contrary to the main MicroVG C module, they are optional: when they are not available, the default implementation of drawings is used. +The default implementation does nothing (no drawing) and throws the :ref:`drawing log` ``DRAWING_LOG_NOT_IMPLEMENTED``. + +These C Modules fetches automatically by transitivity the generic MicroUI and MicroVG C modules and the :ref:`Extended C Module` for the selected GPU. + +The next tables summarizes the VG Packs with: * the UI Pack (see upper), +* the specific C module that implements MicroVG over the GPU (called ``VG-xxx`` in next tables), +* the specific C module that implements MicroUI over the GPU (called ``UI-xxx`` in next tables), see :ref:`section_ui_releasenotes_cmodule_extended`, +* the VG Pack C module, * the UI Pack C module: see :ref:`UI Pack `, -* and by consequence, the specific C module MicroUI over VGLite: see :ref:`section_ui_c_module_microui_vglite`. - -The following table describes the compatibility ranges between the VG Packs and the C modules (generic and specific): - -+---------------+---------+----------+----------+----------------+----------------+ -| VG Pack | MicroVG | FreeType | Harfbuzz | MicroUI-VGLite | MicroVG-VGLite | -+===============+=========+==========+==========+================+================+ -| 1.5.0 | 5.0.0 | 2.0.2 | 1.0.2 | 8.0.0 | 7.0.0 | -+---------------+---------+----------+----------+----------------+----------------+ -| 1.4.2 | 4.0.0 | 2.0.2 | 1.0.2 | 7.2.0 | 6.1.1 | -+---------------+---------+----------+----------+----------------+----------------+ -| [1.4.0-1.4.1] | 3.0.1 | 2.0.2 | 1.0.2 | [7.0.0-7.1.0] | [6.0.0-6.1.0] | -+---------------+---------+----------+----------+----------------+----------------+ -| 1.3.0 | 3.0.0 | 2.0.2 | 1.0.2 | 6.0.1 | 5.0.1 | -+---------------+---------+----------+----------+----------------+----------------+ -| [1.2.0-1.2.1[ | 2.1.0 | 2.0.2 | 1.0.2 | 5.0.1 | 4.0.4 | -+---------------+---------+----------+----------+----------------+----------------+ -| [1.1.0-1.1.1[ | 2.0.0 | 2.0.2 | 1.0.2 | 3.0.0 | 3.0.2 | -+---------------+---------+----------+----------+----------------+----------------+ -| [1.0.0-1.1.0[ | n/a | n/a | n/a | n/a | n/a | -+---------------+---------+----------+----------+----------------+----------------+ - -.. note:: The C module ``MicroVG over VGLite`` fetches automatically by transitivity the other C modules. No need to fetch explicitly the different modules (except the C module ``Harfbuzz``). An update of this C module also updates (if necessary) the other C modules. +* Freetype and Harfbuzz + +.. warning:: Compatible versions are more restrictive than for use of the UI pack (and its C modules) alone. + +**Vivante VGLite** + +The :ref:`VGLite C module ` targets the NXP CPU that provides the Vivante VGLite accelerator. + +The following table describes the version compatibility between the MicroEJ VG Packs, the UI Packs, the generic C modules and the VGLite C modules: + ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| VG Pack | UI Pack | VG-VGLite | UI-VGLite | MicroVG C Module | MicroUI C Module | FreeType | Harfbuzz | Comment | ++===============+=================+===============+===========+==================+==================+==========+==========+=========================+ +| 1.6.0 | [14.0.1-14.0.2] | 8.0.1 | 9.0.0 | 6.0.1 | 4.1.0 | 3.0.0 | 2.0.0 | VG Pack extensibility | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| 1.5.1 | [14.0.0-14.0.2] | 7.0.1 | 8.0.1 | 5.0.0 | 4.0.1 | 2.0.2 | 1.0.2 | Scissor issue | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| 1.5.0 | [14.0.1-14.0.2] | 7.0.1 | 8.0.1 | 5.0.0 | 4.0.1 | 2.0.2 | 1.0.2 | C modules harmonization | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| 1.5.0 | 14.0.0 | 7.0.0 | 8.0.0 | 5.0.0 | 4.0.0 | 2.0.2 | 1.0.2 | UI Pack major version | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| 1.4.2 | [13.7.0-13.7.2] | 6.1.1 | 7.2.0 | 4.0.0 | 3.1.1 | 2.0.2 | 1.0.2 | Very long paths | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| [1.4.0-1.4.1] | [13.7.0-13.7.2] | [6.0.0-6.1.0] | 7.2.0 | 3.0.1 | 3.1.0 | 2.0.2 | 1.0.2 | Free image resources | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| [1.4.0-1.4.1] | [13.5.1-13.6.2] | 6.1.0 | 7.1.0 | 3.0.1 | 3.0.0 | 2.0.2 | 1.0.2 | VGLite `3.0.15_rev7` | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| 1.4.0 | [13.5.1-13.6.2] | 6.0.0 | 7.0.0 | 3.0.1 | 3.0.0 | 2.0.2 | 1.0.2 | Blend modes | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| 1.3.0 | [13.5.1-13.6.2] | 5.0.1 | 6.0.1 | 3.0.0 | 3.0.0 | 2.0.2 | 1.0.2 | Buffered vector image | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| 1.2.1 | [13.3.0-13.4.1] | 4.0.3 | 5.0.1 | 2.1.0 | 2.0.1 | 2.0.2 | 1.0.2 | Image raw format | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ +| 1.1.1 | [13.3.0-13.4.1] | 3.0.2 | 3.0.0 | 2.0.0 | 2.0.0 | 2.0.2 | 1.0.2 | | ++---------------+-----------------+---------------+-----------+------------------+------------------+----------+----------+-------------------------+ + +**Think Silicon NemaGFX** + +The :ref:`NemaGFX C module ` targets the CPU that provides the NemaGFX accelerator. + +The following table describes the version compatibility between the MicroEJ VG Packs and the C modules: + ++---------+-----------------+-----------+---------+------------------+------------------+----------+----------+---------+ +| VG Pack | UI Pack | VG-NemaVG | UI-Nema | MicroVG C Module | MicroUI C Module | FreeType | Harfbuzz | Comment | ++=========+=================+===========+=========+==================+==================+==========+==========+=========+ +| 1.6.0 | [14.0.1-14.0.2] | 1.0.1 | 3.0.0 | 6.0.1 | 4.1.0 | 3.0.0 | 2.0.0 | | ++---------+-----------------+-----------+---------+------------------+------------------+----------+----------+---------+ .. - | Copyright 2008-2024, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/vgSimulation.rst b/VEEPortingGuide/vgSimulation.rst index 05c0825a4..b4cdfe992 100644 --- a/VEEPortingGuide/vgSimulation.rst +++ b/VEEPortingGuide/vgSimulation.rst @@ -7,14 +7,80 @@ Simulation Principle ========= -The VG Pack embeds an extension of :ref:`UI Pack's Front Panel mock ` to implement the equivalent of the five embedded modules (Matrix, Path, Gradient, Image and Font). +The VG Pack embeds an implementation of the :ref:`UI Pack's Front Panel mock ` that implements the equivalent of the five embedded modules (Matrix, Path, Gradient, Image and Font). +This implementation has to be extended to simulate the same characteristics and limitations as the embedded modules. +The aim of this extension is to: -The implementation simulates the same characteristics and limitations as the embedded modules. +* decode the images encoded for a specific GPU (see :ref:`section_vg_image_generator`) +* simulate the limitations of the MicroVG implementation over a GPU (unsupported blend modes, MicroUI drawings in a ``BufferedVectorImage``, etc.). + +Default Extensions +================== + +Two extensions are available that simulate the Vivante VGLite (compatible with the :ref:`section_vg_c_module_microvg_vglite`) and Think Silicon NemaVG (compatible with the :ref:`section_vg_c_module_microvg_nema`) GPUs. +To select one of them, set the right name (respectively ``vglite`` and ``nema``) in the VEE Port configuration file (see :ref:`section_microvg_installation`). + +.. _section_vg_frontpanel_extension: + +Custom Extension +================ + +Overview +-------- + +A custom extension can be selected to simulate another GPU. +This extension consists of the implementation of several interfaces and classes. +In the VEE Port's Front Panel project: + +1. Add the dependency: + + .. code-block:: xml + + + + + + Where ``x.y.z`` is the VG Pack version used to build the VEE Port (minimum ``1.6.0``). +2. Implement one or several interfaces / classes to simulate the embedded GPU (see next chapters). +3. Rebuild the VEE Port. + +Image Decoder +------------- + +To decode the images generarated by the :ref:`image generator`, implement the interface ``ej.microvg.image.ImageDecoder`` in the VEE Port's Front Panel project. +The name of the class must be ``ej.microvg.image.[Prefix]ImageDecoder`` where ``[Prefix]`` is the name that will be set in the VEE Port configuration file (see :ref:`section_microvg_installation`). + +.. note:: This implementation is mandatory to allow the use of encoded images. + +Display Drawer +-------------- + +This feature allows to simulate the same limitations of the GPU to draw the MicroVG drawings (path, gradient, blend modes, etc.) in the display buffer (and in the ``BufferedImage`` with same format than the display buffer). + +.. note:: This implementation is optional; by default, all the MicroVG drawings are implemented. + +1. Extend the class ``ej.microvg.display.DisplayDrawer``; the name of the class must be ``ej.microvg.display.[Prefix]DisplayDrawer`` where ``[Prefix]`` is the name that will be set in the VEE Port configuration file (see :ref:`section_microvg_installation`). +2. Override the method ``drawPath()`` to simulate some limitations. + +Buffered Vector Image +--------------------- + +On the embedded side, the MicroUI drawings (line, rectangle, etc.) must be explicitly implemented to be stored in a ``BufferedVectorImage`` (a drawing should not be stored if the GPU is not able to render it). +The Front Panel extension allows to simulate the same limitations. + +.. note:: This implementation is optional; by default, all the MicroUI drawings in a BufferedVectorImage are disabled (whereas all the MicroVG drawings are enabled). + +The Front Panel extension already provides an engine that implements all MicroUI drawings in a ``BufferedVectorImage``. +Each drawing of this extension can be used independently to simulate the behavior of the embedded side. + +1. Implement the interface ``ej.microvg.bvi.BufferedVectorImageDrawer``; the name of the class must be ``ej.microvg.bvi.[Prefix]BufferedVectorImageDrawer`` where ``[Prefix]`` is the name that will be set in the VEE Port configuration file (see :ref:`section_microvg_installation`). +2. Implement one or several MicroUI drawing methods. +3. Call the corresponded engine's drawing method, for instance: ``LLVGEngine.Instance.getBufferedVectorImageDrawer().fillRectangle(xxx)``. Installation ============ -No action is required in the VEE Port's Front Panel project: the MicroVG simulation part is automatically used when an application uses MicroVG APIs on the simulator. +Refer to the chapter :ref:`section_microvg_installation` for more information about the front panel configuration. Use === diff --git a/VEEWearUserGuide/android/projectSetup.rst b/VEEWearUserGuide/android/projectSetup.rst index 25f394aef..c44aa0de3 100644 --- a/VEEWearUserGuide/android/projectSetup.rst +++ b/VEEWearUserGuide/android/projectSetup.rst @@ -1,7 +1,7 @@ .. _ack_create_project_: .. |ACK_PLUGIN_VERSION| replace:: 0.3.6 -.. |SDK_VERSION| replace:: 0.16.0 +.. |SDK_VERSION| replace:: 0.17.0 .. |SUPPORT_LIB_VERSION| replace:: 2.0.1 Project Setup diff --git a/VEEWearUserGuide/images/vee-script-flow.png b/VEEWearUserGuide/images/vee-script-flow.png new file mode 100644 index 000000000..943b5fbd8 Binary files /dev/null and b/VEEWearUserGuide/images/vee-script-flow.png differ diff --git a/VEEWearUserGuide/index.rst b/VEEWearUserGuide/index.rst index 4c8a56453..02eb7f27a 100644 --- a/VEEWearUserGuide/index.rst +++ b/VEEWearUserGuide/index.rst @@ -62,6 +62,7 @@ For further information about the MicroEJ and Facer partnership, please contact android/index ick offloading + veescript .. | Copyright 2008-2024, MicroEJ Corp. Content in this space is free diff --git a/VEEWearUserGuide/veescript.rst b/VEEWearUserGuide/veescript.rst new file mode 100644 index 000000000..42f9b1312 --- /dev/null +++ b/VEEWearUserGuide/veescript.rst @@ -0,0 +1,145 @@ +.. _veescript: + +VEE Script +========== + +Introduction +------------ + +VEE Script is a scripting language supported on MICROEJ VEE. + +Its syntax is a subset of JavaScript. +This subset includes most expressions but excludes statements and blocks. + +The strengths of VEE Script are its low footprint, its optimized performance, its customizable semantics and its ability to evaluate expressions depending on the runtime context. + +To have the best runtime performance, expressions are preprocessed offboard. +During this phase, expressions are parsed, converted into `ASTs `_ and serialized into a binary file. +At runtime, the ASTs are deserialized from the binary file and the expressions can be evaluated efficiently. + +.. figure:: images/vee-script-flow.png + :alt: Preprocessing and Interpretation Flow + :align: center + + Preprocessing and Interpretation Flow + +VEE Script can be used for various use cases, including the design and rendering of dynamic GUIs and real-time information displays. +For instance, VEE Script is currently used in the VEE Wear Kernel to design and render watchfaces. + +Tags and Functions +------------------ + +VEE Script introduces tags and functions, which can be evaluated to different values depending on the runtime context. +For example, a "*current time*" tag or a "*generate random value*" function would return a different value every time they are interpreted. + +Moreover, tags and functions semantics are defined by the product. +This allows every product to define its own `DSL `_, specific to the type of device and to its unique features. +For example, a smartwatch could introduce a tag for battery level while a washing machine could introduce a tag for remaining cycle time. + +Examples +-------- + +For example, the following script could be used to display the heart rate: + +.. code-block:: javascript + + product.evaluateTag('heart_rate') + ' BPM' + +And the following script could be used to animate the position of a widget: + +.. code-block:: javascript + + 100 * product.applyFunction('sin', product.evaluateTag('current_time') / 1000 * 3.14) + +Expression Types +---------------- + +VEE Script supports the following expression types: + +- literal +- unary operation (+, -) +- binary operation (\*, /, %, +, -, <, >, <=, >=, ==, !=, &&, ||) +- conditional (?:) +- tag evaluation +- function application + +Value Types +----------- + +Once an expression is evaluated, its value has one of the following types: + +- boolean +- number +- string + +Language Syntax +--------------- + +The scripting language is a subset of JavaScript. +Its syntax and semantics are specified by `ECMAScript 5.1 `_. + +The following table summarizes the grammar rules of the language: + +.. list-table:: + :widths: auto + :header-rows: 1 + + * - Grammar Rule + - Example + - Expression Type + * - ** + - *true* + - Boolean literal + * - ** + - *3.5* + - Number literal + * - *''* + - *'hello world'* + - String literal + * - * * + - *-10* + - Unary operation + * - * * + - *1 + 2* + - Binary operation + * - * ? : * + - *2 > 1 ? 5 : 10* + - Conditional + * - *product.evaluateTag('')* + - *product.evaluateTag('battery')* + - Tag evaluation + * - *product.applyFunction('', [expressions])* + - *product.applyFunction('sqrt', 9)* + - Function application + * - *product.constants.* + - *product.constants.pi* + - Literal + +Language Configuration +---------------------- + +Since the semantics of the language depend on the product, the expression parser and interpreter must be configured. + +The following information must be supplied to the parser: + +- the name and value of every constant +- the name of every tag +- the name of every function + +The following information must be supplied to the interpreter: + +- the semantics of every tag +- the semantics of every function + +Evaluation +---------- + +The VEE Script parser and interpreter are available on demand. +You can contact :ref:`MicroEJ Support` to evaluate this solution. + +.. + | Copyright 2008-2024, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/conf.py b/conf.py index 40e82d16f..918d44765 100644 --- a/conf.py +++ b/conf.py @@ -83,15 +83,23 @@ # setting for pygments. This is the same style class used by the HTML builder. pygments_style = 'microej.MicroEJStyle' -# ignoring Github links with anchors at linkcheck -# linkcheck_ignore = [r'https?:\/\/github\.com\/.+#.+'] - +# Have linkcheck ignore all links except those : +# - starting with a "#" (inner references) +# - containing "microej.com" (main website, docs, developer, repository, forge...) +# - containing "github.com/MicroEJ" +# - containing "nxp.com" +# - containing "facer.io" +linkcheck_ignore = [r'^(?!#|.*microej\.com|.*nxp\.com|.*facer\.io|.*github\.com\/MicroEJ)'] + +# Keep these legacy linkcheck_ignore patterns for occasional monitoring of external links # Ignore some links: -# - local index links flagged as broken by linkcheck. Hopefully temporary solution +# - local index links flagged as broken by linkcheck. Hopefully temporary solution # until https://github.com/sphinx-doc/sphinx/issues/9383 is resolved. # - unstable URLs which make the link check fail, such as www.gnu.org or www.oracle.com # - https://forum.segger.com does not provide its CA certificates # - https://site.mockito.org DNS failure (2024/02/12) -linkcheck_ignore = [r'^((?!:\/\/|#|@).)*$|^https://www\.gnu\.org/software/gettext/manual/.*$|^http://localhost.*$|^http://172.17.0.1.*$|^https://www.oracle.com/.*$|^https://forum.segger.com/.*$|^https://site.mockito.org.*$'] +#linkcheck_ignore = [r'^((?!:\/\/|#|@).)*$|^https://www\.gnu\.org/software/gettext/manual/.*$|^http://localhost.*$|^http://172.17.0.1.*$|^https://www.oracle.com/.*$|^https://forum.segger.com/.*$|^https://site.mockito.org.*$|^https://helpx.adobe.com/illustrator/using/simplify_paths.html$'] +# ignoring Github links with anchors at linkcheck +#linkcheck_ignore = [r'https?:\/\/github\.com\/.+#.+'] linkcheck_timeout = 20