Platform Package reference: Function EwSetStackAddressArea()
Description of the function EwSetStackAddressArea() available in all Platform Packages for C compatible target systems. This function is intended to be used when integrating the Embedded Wizard created GUI application with the underlying graphics subsystem, graphics hardware or other external GUI applications coexisting on the same system.
IMPORTANT
Please note, with version 12 the function EwSetStackAddressArea() replaces the preceding function EwSetStackBaseAddress(). The function EwSetStackBaseAddress() is not available anymore.
Declaration
void EwSetStackAddressArea( void* aStackBaseAddress, void* aStackEndAddress )
Parameters
aStackBaseAddress
Base address of the CPU stack used by Embedded Wizard application.
aStackEndAddress
The address at the opposite end of the CPU stack used by Embedded Wizard application.
Discussion
The function EwSetStackAddressArea() remembers the given values as base and end addresses of the CPU stack used by Embedded Wizard application. Knowing this the Garbage Collector can be started while the application is executing code and can evaluate stack contents in order to mark Chora objects and strings stored on it actually. It is also useful to perform checks and report errors if the application is running out the CPU stack memory or Embedded Wizard core functions are invoked in context of a foreign task/thread (task/thread using other stack memory area).
Usually, the garbage collection is performed at the end of a screen update by invoking the function EwReclaimMemory(). Running the garbage collection while the application is actually executing code is problematic because references to Chora objects or strings stored locally on the CPU stack or in CPU registers can't be taken in account. From this arises the problem, that memory reserved for Chora objects or strings remains occupied until the screen update is done. The probability for an out of memory issue increases.
With the introduction of so-called immediate garbage collection this problem is solved. If the application is running in an out of memory problem, the garbage collection can be started immediately. For this purpose, however, the Garbage Collector needs to know the contents of the CPU stack. By invoking the function EwSetStackAddressArea() at the initialization time of your application you can inform the Garbage Collector about the stack area.
Please note, the value passed in the parameter aStackBaseAddress has to refer the address from which the stack starts to grow. The correct address calculation and the stack growing direction may depend on the CPU architecture, the operating system and the used C compiler. In turn, the value passed in the parameter aStackEndAddress has to refer the address where the stack memory ends. The memory between aStackBaseAddress and aStackEndAddress determines the corresponding stack area. Take in account following aspects:
★If the stack is growing downwards (in direction of lower addresses), the base address is on top of the stack. aStackBaseAddress refers thus the highest possible stack address. Consequently aStackEndAddress is equal to aStackBaseAddress - stack size. Stacks growing downwards are the most usual case.
★If the stack is growing upwards (in direction of higher addresses), the base address is on bottom of the stack. aStackBaseAddress refers thus the lowest possible stack address. Consequently aStackEndAddress is equal to aStackBaseAddress + stack size. Stacks growing upwards are less common.
★If you are using an operating system, the stack memory associated to a task or thread may eventually be allocated dynamically just in the moment when the task or thread is created. In such case you have to query the stack base address by using an adequate operating system function. It is essential that the provided addresses refer the stack associated to the task or thread running the GUI application. Don't pass the addresses referring the operating system's own stack. It is not the stack used by the tasks or threads!
IMPORTANT
To use the immediate garbage collection please ensure that the Runtime Environment and Graphics Engine are compiled with the macro EW_USE_IMMEDIATE_GARBAGE_COLLECTION being defined in your make file. If you are using one of our prepared Build Environments you can configure this macro in the file ewconfig.h. However, Platform Packages contained in the Small Business edition of Embedded Wizard are provided as libraries compiled without this macro resulting in this function not being available. Similar is true if you are using an Evaluation edition of a Platform Package.