Platform Integration Aspects: Target Configuration

All settings that affect the GUI application and code generation can be made directly in the profile, such as selecting the Platform Package, the desired color format or the screen size. During system integration, additional settings are required to embed the GUI application in a real target. The existing hardware capabilities should be used in an optimal manner, but all hardware restrictions and limited system resources must also be kept in mind.

The file ewconfig.h that is provided within all Build Environments for dedicated targets is the central location for all target specific settings. It contains general configuration settings for the target system, like memory ranges and display parameter and configuration settings for the Embedded Wizard Graphics Engine and Runtime Environment.

This article describes the available target configurations and options that are applicable for most MCU and MPU targets.

IMPORTANT

Please note that the available configuration settings differ from target to target. Some of the definitions listed here may not affect your system - or additional specific settings (not listed here) may be used on other systems. Please take a look at the ewconfig.h file provided in the Build Environment you are using.

Build Environment Identification

The following macros identifies the target platform and the version of the used Build Environment.

Macro

Description

EW_PLATFORM_STRING

This macro contains the name of the development platform and identifies the used Build Environment.

EW_BUILD_ENV_VERSION

Version string of the Embedded Wizard Build Environment.

Application and Platform Configuration

The following macros configure the application. In case of MCUs, a set of macros are provided to define RAM areas, RTC values and settings for an external flash.

Macro

Description

EW_USE_TERMINAL_INPUT

Flag to switch on/off the support of keyboard events received from a connected serial terminal.

SDRAM_BASE_ADDR, SDRAM_SIZE_BYTES

These macros define the start address and the size of the external memory (SDRAM) that can be used for framebuffer(s) and the heap manager.

SRAM_BASE_ADDR, SRAM_SIZE_BYTE

These macros define the start address and the size of the internal memory (SRAM) that can be used for framebuffer(s).

EW_CPU_LOAD_MEASURING

Flag to switch on/off the measuring of the CPU load caused by the GUI application and all graphics operations. The CPU load can be read by using the function EwBspClockGetCpuLoad().

RTC_MINIMUM_TIME, RTC_DEFAULT_TIME

Macros to define the initialization value of the realtime clock (RTC). The value RTC_DEFAULT_TIME is used as start value for the RTC in case that it is not already initialized with a value higher than RTC_MINIMUM_TIME.

EW_USE_EXTERNAL_FLASH

Flag to enable/disable the usage of the external FLASH device.

EW_BITMAP_PIXEL_SECTION_NAME

Macro to define the section name for the bitmap pixel data of bitmap resources. The section name is used in the linker file to locate the data to a dedicated read-only memory area.

EW_FONT_PIXEL_SECTION_NAME, EW_FONT_DATA_SECTION_NAME

Macros to define the section name for font pixel data and font metrics of font resources. The section names are used in the linker file to locate the data to a dedicated read-only memory area.

EW_CONST_STRING_SECTION_NAME

Macro to define the section name for all string constants. The section name is used in the linker file to locate the data to a dedicated read-only memory area.

Display Integration and Framebuffer Access

The following macros configure display integration, framebuffer access, and use of a graphics accelerator (GPU). Depending on the display controller used and the display memory access supported, only a few settings may be supported on your particular target system. See supported framebuffer concepts for more details.

Macro

Description

EW_USE_SCRATCHPAD_BUFFER

Flag to switch on/off the usage of a small scratch-pad buffer used for the graphics composition instead of a framebuffer. As a result the screen of the display is updated in partial mode. This mode is used to reduce the memory footprint to a minimum, but it may cause some tearing or flickering effects. This mode is useful in combination with displays containing its own graphics memory (GRAM).

EW_USE_DOUBLE_BUFFER

Flag to switch on/off the usage of an additional framebuffer, so that the screen is operated in double-buffering mode. If double-buffering is activated, the exchange between front-buffer and back-buffer has to be done at V-sync. This has to be implemented in the function EwBspDsipalyCommitBuffer(). In case of a single buffered configuration, the graphics composition is done directly into the framebuffer. This makes only sense, if you are using an LCD with its own pixelbuffer (e.g. some MIPI-DSI displays). Otherwise, the composition of the framebuffer content has to be synchronized with the LCD update in order to avoid flickering.

EW_USE_OFFSCREEN_BUFFER

Flag to switch on/off the usage of an additional off-screen buffer. This is an internal buffer, allocated by the Graphics Engine and used to prepare the graphical content (composition buffer). The usage of a separate off-screen buffer might be advantageous on systems where the read access from the physical framebuffer is very slow. In this case, the off-screen buffer is used for composition (read and write access) and the final graphics is then copied into the framebuffer (write access).

EW_DISPLAY_WIDTH, EW_DISPLAY_HEIGHT

These macros define the physical dimension of the display in pixel. Typically this corresponds to the attribute ScreenSize defined within the Profile of the Embedded Wizard GUI project.

EW_FRAME_BUFFER_WIDTH, EW_FRAME_BUFFER_HEIGHT

These macros define the size of the framebuffer in pixel. Typically this size corresponds to the size of the display. However, due to hardware requirements or necessary memory alignments, the size of the framebuffer might differ from the display size.

EW_FRAME_BUFFER_ADDR, EW_FRAME_BUFFER_SIZE

These macros define the start address and the size (in bytes) of the framebuffer.

EW_DOUBLE_BUFFER_ADDR, EW_DOUBLE_BUFFER_SIZE

These macros define the start address and the size (in bytes) of the optional double-buffer.

EW_USE_GRAPHICS_ACCELERATOR

Flag to switch on/off the usage of the graphics accelerator (GPU) within the target (if available). Please note: Changing this macro requires the complete source code of the Graphics Engine to be recompiled with the new setting. As such it works only for customers who have licensed the 'Professional' edition.

EW_VIEWPORT_AUTOSCALE

If set to 1, the current display size is used as viewport size to show the GUI application in full screen mode. Otherwise the ScreenSize defined in the Embedded Wizard GUI project will be used as viewport size. This macro affects only platorms based on OpenGL ES 2.0

EW_VIEWPORT_ROTATION

This macro defines the viewport rotation in degrees. Possible values are 0, 90, 180 and 270. This macro affects only platforms based on OpenGL ES 2.0. For all other architectures, the rotation of the GUI application can be achieved by using the attribute ScreenOrientation.

EW_PERFORM_FULLSCREEN_UPDATE

This setting forces the OpenGL driver to clear the entire framebuffer before starting a new screen update. If this option is set 1, the Mosaic framework will redraw the entire screen each time something changes on the screen. The explicit clear may improve the overall performance depending on the GPU hardware.

EW_PERFORM_FULLOFFSCREENBUFFER_UPDATE

This setting forces the OpenGL driver to clear an off-screen frame buffer before starting to drawing it. If this option is set 1, the Mosaic framework will redraw the entire content of the off-screen buffer each time something changes in its area. The explicit clear may improve the overall performance depending on the GPU hardware.

EW_BORDER_AROUND_GLYPHS

If set to 1, the Graphics Engine reserves an additional one pixel wide border around each glyph within the glyph cache. This is useful, when glyphs are scaled by the GPU hardware.

Touch Device Configuration

Typically, with MCUs, the touch events are read directly from the touch driver - with MPUs or systems with a windowing system (e.g. Wayland, Windows, Android), the touch coordinates are provided by the operating system. The following macros configure the integration of touch devices.

Macro

Description

EW_TOUCH_AREA_MIN_X

This macro defines the raw touch value of the leftmost position on the touch screen. This value represents the x value reported by the touch driver when touching on the top left corner of the display.

EW_TOUCH_AREA_MIN_Y

This macro defines the raw touch value of the topmost position on the touch screen. This value represents the y value reported by the touch driver when touching on the top left corner of the display.

EW_TOUCH_AREA_MAX_X

This macro defines the raw touch value of the rightmost position on the touch screen. This value represents the x value reported by the touch driver when touching on the bottom right corner of the display.

EW_TOUCH_AREA_MAX_Y

This macro defines the raw touch value of the bottommost position on the touch screen. This value represents the y value reported by the touch driver when touching on the bottom right corner of the display.

EW_TOUCH_SWAP_XY

This macro can be used to exchange the x and y values provided by the touch driver.

EW_PRINT_TOUCH_DATA

This macro prints all touch data reported by the touch driver on the console. This is helpful to test and calibrate the touch device.

EW_PRINT_TOUCH_EVENTS

This macro prints all touch events that are provided to the GUI application. This macro is important for testing during development: Every touch cycle for each finger has to start with one DOWN event followed by 0...n MOVE events and it has to be finalized with one UP event. This sequence is essential and mandatory to provide touch events to the GUI application.

Memory Configuration

The following macros configure the memory areas used for the Embedded Wizard GUI application. The memory pool settings are used for the initialization of the heap manager by using the functions EwInitHeap() and EwAddHeapMemoryPool().

Macro

Description

EW_MEMORY_POOL_SECTION

This macro has to be defined if the memory pool shall be declared as an array. Optionally a linker section name can be assigned to this macro to define where this array shall be located by the linker. Alternatively, a fixed memory address can be defined by setting the macro EW_MEMORY_POOL_ADDR.

EW_MEMORY_POOL_ADDR

This macro defines the start address of the memory pool to a fixed address. Take care that the memory area is not used by the linker. Do not use this define in combination with EW_MEMORY_POOL_SECTION.

EW_MEMORY_POOL_SIZE

This macro defines the size of the memory pool in bytes used for the Embedded Wizard heap manager.

EW_EXTRA_POOL_SECTION

This macro can be used to define a second (additional) memory pool. Same as EW_MEMORY_POOL_SECTION

EW_EXTRA_POOL_ADDR

This macro can be used to define a second (additional) memory pool. Same as EW_MEMORY_POOL_ADDR

EW_EXTRA_POOL_SIZE

This macro can be used to define a second (additional) memory pool. Same as EW_MEMORY_POOL_SIZE

EW_GUI_THREAD_STACK_SIZE

This macro defines the stack size (in bytes) of the main GUI thread/task: In case that an operating system is used and the stack is allocated in the moment when the GUI thread/task is created, the macro defines the exact size of memory allocated for the stack. In case the stack size is predefined by linker settings, this macro defines only the stack size that will be considered and checked as stack of the GUI application - even if the real stack size is larger. In case of a bare metal environment the setting has no meaning.

Profiling, Tracing and Optimization

The following macros configure advance aspects of an Embedded Wizard application used for profiling, tracing or optimization purpose. In order to enable the functionality uncomment the respective macro definitions within ewconfig.h.

Macro

Description

EW_PRINT_MEMORY_USAGE

If this macro is defined, a statistic information is printed reporting the amount of memory allocated by Chora objects, strings and resources. Additionally, the current total memory allocation and the maximum peak value is printed. This feature is very helpful to monitor the real data memory (RAM) usage on the target

EW_DUMP_HEAP

If this macro is defined, the contents of all memory pools are evaluated and the associated information as well as the existing blocks are reported.

EW_SUPPORT_GFX_TASK_TRACING

If this macro is defined, the functions of the Graphics Engine are enhanced by code to track and protocol all drawing tasks executed at the runtime. Once the functionality is available, you control the outputs of the traced drawing operations by using the EwEnableGfxTaskTracing() function. Please note: Activating this macro requires the complete source code of the Graphics Engine to be recompiled with the new setting. As such it works only for customers who have licensed the 'Professional' edition.

EW_PRINT_GFX_TASKS

Defining this macro activates the above described tracing of drawing tasks as if the macro EW_SUPPORT_GFX_TASK_TRACING were defined and the function EwEnableGfxTaskTracing() to enable the trace outputs were called. This is a convenience macro to simply activate the tracing without needing to modify your application code by additional function calls. Please note: Activating this macro requires the complete source code of the Graphics Engine to be recompiled with the new setting. As such it works only for customers who have licensed the 'Professional' edition.

EW_PRINT_PERF_COUNTERS

If this macro is defined, all essential functions of the Graphics Engine and Runtime Environment are enhanced by additional code to to track and measure their runtime. To display this collected information you use the function EwPrintPerfCounters(). In order to use this feature, it is necessary to provide an exact time in microseconds via EwGetPerfCounter() that you will find in the file ewextrte.c. Please note: Activating this macro requires the complete source code of the Graphics Engine to be recompiled with the new setting. As such it works only for customers who have licensed the 'Professional' edition.

EW_USE_IMMEDIATE_GARBAGE_COLLECTION

If this macro is defined, the process of detection and disposal of unused Chora objects is allowed to run at any time, even when this would interfere with the actually executed Chora code. If this macro is not defined, garbage collection is only performed when no chora code is running - this is guaranteed in the main loop. Using this feature expects, that your application uses the function EwSetStackAddressArea() to inform the Garbage Collector about the memory area occupied by the CPU stack. Please note: Activating this macro requires the complete source code of the Graphics Engine to be recompiled with the new setting. As such it works only for customers who have licensed the 'Professional' edition.

Caches and Buffers Configuration

The following macros configure the size of diverse caches and buffers of the Runtime Environment and the Graphics Engine. Generally, the larger a cache or buffer, the better the performance of the application. On the other hand, large caches and buffers will occupy more RAM. Configure the macros prudently according to the available RAM and expected performance.

Macro

Description

EW_MAX_STRING_CACHE_SIZE

This macro specifies the threshold value for the capacity of the string cache. The string cache stores frequently used string constants preventing them from being reloaded repeatedly. Embedded Wizard tracks the amount of memory occupied by all string constants and as soon as this size exceeds the value specified in the macro, discards oldest unused strings from the cache automatically. The value for this macro is expressed in bytes as an integer number lying between 0 and 0x800000.

EW_MAX_SURFACE_CACHE_SIZE

This macro specifies the threshold value for the capacity of the surface cache. This cache stores often used bitmap resources and off-screen image buffers preventing them from being reloaded or recreated repeatedly. Embedded Wizard tracks the amount of memory occupied by all cached surfaces and as soon as this size exceeds the value specified in the macro, discards oldest unused surfaces from the cache automatically. The value for this macro is expressed in bytes as an integer number lying between 0 and 0x20000000.

EW_MAX_GLYPH_SURFACE_WIDTH, EW_MAX_GLYPH_SURFACE_HEIGHT

These macros specify the dimension of the glyph cache surface. This surface stores all glyphs used during text drawing operations. The larger the surface the more glyphs can be reused without needing to decompress or rasterize them again. The values for the macros are expressed in pixel as integer numbers lying between 64 and the maximum surface size supported on the graphics hardware. You should ensure, that the glyph surface is at least as large as the biggest glyph you want to display at the runtime. The following quotation can be used to calculate the approximated RAM usage resulting from the configuration of the macros: ( EW_MAX_GLYPH_SURFACE_WIDTH * EW_MAX_GLYPH_SURFACE_HEIGHT ) * 1 Byte.

EW_MAX_NO_OF_GLYPHS

This macro determines the number of glyphs the Graphics Engine is allowed to store simultanously. The more glyphs are possible the more efficient are all text rasterization and calculation operations. One glyph occupies 48 bytes. The value 0 indicates that the maximum number of glyphs will be estimated based on the size of the glyph surface cache.

EW_MAX_ISSUE_TASKS

This macro specifies the capacity of instruction buffers used to store drawing operations. Larger buffers improve the optimization and elimination of superfluous drawing operations. In turn, small buffers cause the drawing process to be often interrupted to flush the prepared operations. The value for this macro is expressed in 'tasks' as an integer number lying between 1 and 8192. You should ensure that the issue buffer is at least as large as the most complex drawing operation performed in your application. The following quotation can be used to calculate the approximated RAM usage resulting from the configuration of the macro: (( EW_MAX_ISSUE_TASKS * 64 ) + 512 ) * 1 Byte.

EW_INVOCATION_QUEUE_SIZE

This macro defines the size of the invocation queue in bytes. The invocation queue is used to record function invocations by using the functions EwInvoke() and EwInvokeCopy() in the context of foreign threads or interrupt service routines and to execute them afterwards in the regular context of the Embedded Wizard GUI application.

Surface Cache and Bitmap Resource Treatment

The following macros configure the behavior of the surface cache and treatment of bitmap resources when these are generated with the setting ModeOfBitmapResources to Compressed. Depending on the configuration, the application will require more or less RAM, which affects accordingly the resulting performance.

Macro

Description

EW_LAZY_LOAD_BITMAPS

This macro controls the loading behavior of compressed bitmap resources. If this macro is defined with the value 0, the resources are loaded immediately and completely into RAM as soon as the application accesses them. Thereupon the bitmaps remain in the surface cache (see above). If this macro is defined with the value 1, the loading of bitmaps is delayed until the application is about to display one frame of the bitmap. In such case this and only this frame is loaded into RAM.

EW_LAZY_LOAD_BITMAPS_IF_ANIMATED_ONLY

This macro, if defined with the value 1, does limit the effect of the above described macro EW_LAZY_LOAD_BITMAPS to resources containing animated bitmaps only. All other bitmaps (single or multiframe but not animated) are loaded immediately regardless of the actual value for the EW_LAZY_LOAD_BITMAPS macro. If this macro is 0, EW_LAZY_LOAD_BITMAPS affects all kinds of bitmap resources.

EW_DISCARD_BITMAPS

This macro controls the lifetime of bitmaps stored in the surface cache (see above). If this macro is configured with the value 1, the system is allowed to discard bitmap resources even if these are still in use. As soon as the surface cache has exceeded the threshold value specified in the macro EW_MAX_SURFACE_CACHE_SIZE and there is no other unused surfaces ready to discard from the cache, the system discards the lazy loaded bitmap resources. Due to this 'swapping' the application can work with significantly less RAM. If this macro is 0, the discarding affects only such surfaces which are really not in use anymore.

EW_DISCARD_BITMAPS_IF_ANIMATED_ONLY

This macro, if defined with the value 1, limits the effect of the above described macro EW_DISCARD_BITMAPS to surfaces containing animated bitmap resources only. All other bitmaps (single or multiframe but not animated) are treated as if the macro EW_DISCARD_BITMAPS were 0. If EW_DISCARD_BITMAPS_IF_ANIMATED_ONLY is 0, EW_DISCARD_BITMAPS affects all kinds of bitmap in similar manner.

EW_DISCARD_BITMAPS_IF_NOT_USED_IN_CURRENT_UPDATE

This macro, if defined with the value 1, limits the effect of the above described macro EW_DISCARD_BITMAPS to surfaces, which have not been used in actual screen update. This prevents the system from reloading one the same bitmap resource multiple times during the running screen update. If this macro is 0, EW_DISCARD_BITMAPS affects all bitmap resources in similar manner.

EW_DISCARD_BITMAPS_IF_NOT_USED_IN_RECENT_UPDATES

This macro, if defined with the value 1, limits the effect of the above described macro EW_DISCARD_BITMAPS to surfaces, which have not been used in actual and the immediately preceding screen updates. This prevents the system from reloading one the same bitmap resource multiple times during running animations. If this macro is 0, the macro EW_DISCARD_BITMAPS affects all bitmap resources in similar manner.

EW_CACHE_OFFSCREEN_SURFACES

This macro controls how to manage surfaces used to buffer off-screen contents (e.g. used by a buffered GUI component). If this macro is defined with the value 1, the off-screen surfaces are retained in the surface cache (see above). Accordingly, frequently used off-screen surfaces can be reused faster without needing to create them again. Defining the macro with the value 0 disables this function causing the off-screen surfaces to be released immediately if not needed anymore.

Additional Check Functions

The following macros remove functionality dedicated to verify the correct function of the application. Removing such functionality makes sense only if you have finalized the development and ensured that your application works correctly. In order to remove the functionality uncomment the respective macro definition in the file ewconfig.h.

Macro

Description

EW_DONT_CHECK_INDEX

If this macro is defined, the code generated by Embedded Wizard (your application code) does not perform any bounds checking when array items are addressed. If this macro is not defined, addressing items outside of an array will result in an adequate error message. Performing bounds checking may affect the performance if the applications uses arrays extensively.

EW_DONT_CHECK_THREAD_CONTEXT

All relevant top-level Runtime Environment and Graphics Engine functions check if a function is called in the context of the main GUI thread/task. To do this, the test compares the current CPU stack address with the stack area of the GUI thread/task. This helps to detect errors in applications running multiple threads/tasks. Using this feature expects, that your application uses the function EwSetStackAddressArea() to inform the system about the memory area occupied by the CPU stack. If this macro is defined, the context thread check is disabled!

Code Reduction

A set of macros can be used to remove function blocks from the Graphics Engine in order to reduce the code size of the resulting binary. Removing functionality makes sense only if you are sure that it is not needed by your application. If the application nevertheless uses the functionality, a runtime error is reported. In order to remove a function block just uncomment the respective macro within the file ewconfig.h.

Please note, that activating the different macros requires the complete source code of the Graphics Engine to be recompiled with the new setting. As such it works only for customers who have licensed the 'Professional' edition. For customers using the 'Small Business' edition or users working with the 'Free' edition, the macros will not have any effect!

Macro

Description

EW_DONT_USE_WARP_FUNCTIONS

If this macro is defined, all functions needed to calculate and display transformed image contents are removed from the binary. In particular, it disables the possibility to scale and rotate images as well as their perspective projection resulting in 3D visual effects.

EW_DONT_USE_PATH_FUNCTIONS

If this macro is defined, all functions needed to calculate and raster vector graphics (to display polygons and paths) are removed from the binary.

EW_DONT_USE_BIDI_FUNCTIONS

If this macro is defined, all functions needed to process bidirectional text, as it is usually required to display right-to-left Arabic or Hebrew scripts, are removed.

EW_DONT_USE_BLUR_FUNCTIONS

If this macro is defined, all filter functions with blur filtering are removed from the binary.

EW_DONT_USE_MASK_FUNCTIONS

If this macro is defined, all filter functions with mask filtering are removed from the binary.

EW_DONT_USE_TINT_FUNCTIONS

If this macro is defined, all filter functions with tint filtering are removed from the binary.

EW_DONT_USE_GRADIENTS

If this macro is defined, all drawing functions for gradients are removed from the binary.

EW_DONT_USE_COMPRESSION

This macro can be defined only if neither compressed bitmaps nor compressed strings are used in the project. Doing this eliminates the compression relevant code from the binary.

EW_DONT_USE_INDEX8_SURFACES

If this macro is defined, the support for Index8 bitmap format is removed. Thereupon creation, loading and displaying of images stored in Index format is not possible anymore.

EW_DONT_USE_RGB565_SURFACES

If this macro is defined, the support for RGB565 bitmap format is removed. Thereupon creation, loading and displaying of images stored in RGB565 format is not possible anymore.

EW_DONT_USE_NATIVE_SURFACES

If this macro is defined, the support for Native bitmap format is removed. Thereupon creation, loading and displaying of images stored in Native format is not possible anymore.

EW_DONT_USE_NATIVE_SURFACES_AS_DESTINATION

If this macro is defined all graphical operations using a Native surface as destination are eliminated. This makes sense only when the alternative destination surface format Screen is defined. Otherwise no graphics outputs are possible.