µOS++ IIIe Reference 7.0.0
The third edition of µOS++, a POSIX inspired open source framework, written in C++
Loading...
Searching...
No Matches
µOS++ Application Overrides & Hooks

µOS++ application customisable functions and hooks. More...

Startup Routines

void _start (void)
 The standard C application entry point.
 
void os_startup_initialize_hardware_early (void)
 Initialise hardware early.
 
void os_startup_initialize_hardware (void)
 Initialise hardware.
 
void os_startup_initialize_free_store (void *heap_address, size_t heap_size_bytes)
 Initialise free store.
 
void os_startup_initialize_args (int *p_argc, char ***p_argv)
 Initialise arguments.
 
void os_startup_create_thread_idle (void)
 Create the idle thread.
 

Termination Routines

void os_terminate_goodbye (void)
 Display statistics and say goodbye before terminating.
 
void os_terminate (int code)
 Terminate the application. There is no more life after this.
 

Hooks

bool os_rtos_idle_enter_power_saving_mode_hook (void)
 Hook to enter a power saving mode.
 
void os_rtos_application_out_of_memory_hook (void)
 Hook to handle out of memory in the application free store.
 
void os_rtos_system_out_of_memory_hook (void)
 Hook to handle out of memory in the RTOS dynamic memory.
 

Compatibility Macros

#define os_initialize_hardware_early   os_startup_initialize_hardware_early
 
#define os_initialize_hardware   os_startup_initialize_hardware
 
#define os_initialize_args   os_startup_initialize_args
 

Detailed Description

µOS++ application customisable functions and hooks.

Applications using µOS++ can customise the behaviour of the system or intercept several events by redefining these functions.

All of them have weak default definitions, providing a reasonable functionality.

Macro Definition Documentation

◆ os_initialize_args

#define os_initialize_args   os_startup_initialize_args

Definition at line 189 of file os-hooks.h.

◆ os_initialize_hardware

#define os_initialize_hardware   os_startup_initialize_hardware

Definition at line 188 of file os-hooks.h.

◆ os_initialize_hardware_early

#define os_initialize_hardware_early   os_startup_initialize_hardware_early

Definition at line 187 of file os-hooks.h.

Function Documentation

◆ _start()

void _start ( void  )

The standard C application entry point.

Parameters
None.
Returns
Does not return.

This is the place where the Cortex-M core will go immediately after reset (the Reset_Handler calls this function).

To reach this location, the reset stack must point to a valid internal RAM area.

Debugging new startup configurations usually begins with placing a breakpoint at _start(), and stepping through the routine.

Definition at line 264 of file startup.cpp.

◆ os_rtos_application_out_of_memory_hook()

void os_rtos_application_out_of_memory_hook ( void  )

Hook to handle out of memory in the application free store.

Parameters
None.
Returns
Nothing.

This function is called when the application memory manager detects an out of memory condition.

This function is usually used to gracefully reset the device.

However, for special memory managers, which do not coalesce automatically, it might be possible to first try to coalesce. If this succeeds, this call can return, and the allocation will be resumed.

Note
Since most allocations are done in critical sections, this function is very likely to be called with the scheduler locked.

Definition at line 299 of file initialise-free-store.cpp.

◆ os_rtos_idle_enter_power_saving_mode_hook()

bool os_rtos_idle_enter_power_saving_mode_hook ( void  )

Hook to enter a power saving mode.

Parameters
None.
Return values
trueThe hook entered a power saving mode.
falseThe hook did not enter a power saving mode.

The hook must check an application specific condition to determine if it is required to enter a power saving mode, and, if necessary, actually enter the desired power saving mode.

The application must ensure that all interrupts associated with the external events used to awake the device are enabled. Usually the RTC is used for this purpose, but other devices too, like USB, GPIO pins, etc may be used to end the power saving mode.

This function is executed by the idle thread on each iteration, and must limit complexity to reasonably levels.

If the user function decides not to enter a power saving mode, it must return false, which will make the idle thread proceed as usual, by entering a shallow sleep waiting for the next interrupt.

Definition at line 69 of file os-idle.cpp.

◆ os_rtos_system_out_of_memory_hook()

void os_rtos_system_out_of_memory_hook ( void  )

Hook to handle out of memory in the RTOS dynamic memory.

Parameters
None.
Returns
Nothing.

This function is called when the RTOS system memory manager detects an out of memory condition.

This function is usually used to gracefully reset the device.

However, for special memory managers, which do not coalesce automatically, it might be possible to first try to coalesce. If this succeeds, this call can return, and the allocation will be resumed.

Note
Since most allocations are done in critical sections, this function is very likely to be called with the scheduler locked.

Definition at line 322 of file initialise-free-store.cpp.

◆ os_startup_create_thread_idle()

void os_startup_create_thread_idle ( void  )

Create the idle thread.

Parameters
None.
Returns
Nothing.

◆ os_startup_initialize_args()

void os_startup_initialize_args ( int *  p_argc,
char ***  p_argv 
)

Initialise arguments.

Parameters
[out]p_argcPointer to argc.
[out]p_argvPointer to argv.

Definition at line 419 of file startup.cpp.

◆ os_startup_initialize_free_store()

void os_startup_initialize_free_store ( void *  heap_address,
size_t  heap_size_bytes 
)

Initialise free store.

Parameters
heap_addressThe first unallocated RAM address (after the BSS).
heap_size_bytesThe free store size.
Returns
Nothing.

◆ os_startup_initialize_hardware()

void os_startup_initialize_hardware ( void  )

Initialise hardware.

Parameters
None.
Returns
Nothing.

This is the default implementation for the second hardware initialisation routine.

It is called from _start(), right after DATA & BSS init, before the static constructors.

The application can redefine it for more complex cases that require custom inits (before constructors), otherwise these inits can be done in main().

Definition at line 126 of file initialize-hardware.c.

◆ os_startup_initialize_hardware_early()

void os_startup_initialize_hardware_early ( void  )

Initialise hardware early.

Parameters
None.
Returns
Nothing.

This is the default early hardware initialisation routine.

It is called right at the beginning of _start(), to switch clocks to higher frequencies and have the rest of the initialisations run faster.

The application can redefine it for more complex cases that requires inits before DATA and BSS init.

It is mandatory on platforms like Kinetis, which start with the watch dog enabled and require an early sequence to disable it.

Also useful on platform with external RAM, that need to be initialised before filling the BSS section.

Definition at line 66 of file initialize-hardware.c.

◆ os_terminate()

void os_terminate ( int  code)

Terminate the application. There is no more life after this.

Parameters
[in]codeExit code, 0 for success, non 0 for failure.
Returns
Nothing.

◆ os_terminate_goodbye()

void os_terminate_goodbye ( void  )

Display statistics and say goodbye before terminating.

Parameters
None.
Returns
Nothing.

Definition at line 193 of file os-main.cpp.