µ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

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 178 of file os-hooks.h.

os_initialize_hardware

#define os_initialize_hardware   os_startup_initialize_hardware

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

os_initialize_hardware_early

#define os_initialize_hardware_early   os_startup_initialize_hardware_early

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

Function Documentation

_start()

void _start

(

void

)

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 241 of file startup.cpp.

{
  // After Reset the Cortex-M processor is in Thread mode,
  // priority is Privileged, and the Stack is set to Main.
 
  // --------------------------------------------------------------------------
 
  // Initialise hardware right after reset, to switch clock to higher
  // frequency and have the rest of the initialisations run faster.
  //
  // 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.
 
  os_startup_initialize_hardware_early ();
 
  // Use Old Style DATA and BSS section initialisation,
  // that will manage a single BSS sections.
 
#if defined(DEBUG) && (OS_BOOL_STARTUP_GUARD_CHECKS)
 
  __data_begin_guard = DATA_GUARD_BAD_VALUE;
  __data_end_guard = DATA_GUARD_BAD_VALUE;
 
#endif
 
#if !defined(OS_INCLUDE_STARTUP_INIT_MULTIPLE_RAM_SECTIONS)
 
  // Copy the DATA segment from Flash to RAM (inlined).
  os_initialize_data (&_sidata, &_sdata, &_edata);
 
#else
 
  // Copy the data sections from flash to SRAM.
  for (unsigned int* p = &__data_regions_array_start;
       p < &__data_regions_array_end;)
    {
      unsigned int* from = (unsigned int*)(*p++);
      unsigned int* region_begin = (unsigned int*)(*p++);
      unsigned int* region_end = (unsigned int*)(*p++);
 
      os_initialize_data (from, region_begin, region_end);
    }
 
#endif
 
#if defined(DEBUG) && (OS_BOOL_STARTUP_GUARD_CHECKS)
 
  if ((__data_begin_guard != DATA_BEGIN_GUARD_VALUE)
      || (__data_end_guard != DATA_END_GUARD_VALUE))
    {
      while (true)
        {
          __NOP ();
        }
    }
 
#endif
 
#if defined(DEBUG) && (OS_BOOL_STARTUP_GUARD_CHECKS)
 
  __bss_begin_guard = BSS_GUARD_BAD_VALUE;
  __bss_end_guard = BSS_GUARD_BAD_VALUE;
 
#endif
 
#if !defined(OS_INCLUDE_STARTUP_INIT_MULTIPLE_RAM_SECTIONS)
 
  // Zero fill the BSS section (inlined).
  os_initialize_bss (&__bss_start__, &__bss_end__);
 
#else
 
  // Zero fill all bss segments
  for (unsigned int* p = &__bss_regions_array_start;
       p < &__bss_regions_array_end;)
    {
      unsigned int* region_begin = (unsigned int*)(*p++);
      unsigned int* region_end = (unsigned int*)(*p++);
      os_initialize_bss (region_begin, region_end);
    }
 
#endif
 
#if defined(DEBUG) && (OS_BOOL_STARTUP_GUARD_CHECKS)
 
  if ((__bss_begin_guard != 0) || (__bss_end_guard != 0))
    {
      while (true)
        {
          __NOP ();
        }
    }
 
#endif
 
  // Hook to continue the initialisations. Usually compute and store the
  // clock frequency in the global CMSIS variable, cleared above.
  os_startup_initialize_hardware ();
 
  // Initialise the trace output device. From this moment on,
  // trace_printf() calls are available (including in static constructors).
  trace_initialize ();
 
  trace_puts (""); // Empty line
 
  trace_printf ("Hardware initialised\n");
  trace_printf ("Main stack %p-%p\n", &_Heap_Limit, &__stack);
 
  os_startup_initialize_free_store (
      &_Heap_Begin,
      static_cast<size_t> (reinterpret_cast<char*> (&_Heap_Limit)
                           - reinterpret_cast<char*> (&_Heap_Begin)));
 
  // Get the argc/argv (useful in semihosting configurations).
  int argc;
  char** argv;
  os_startup_initialize_args (&argc, &argv);
 
  // Call the standard library initialisation (mandatory for C++ to
  // execute the constructors for the static objects).
  os_run_init_array ();
  trace_printf ("Static objects constructed\n");
 
#if defined(OS_HAS_INTERRUPTS_STACK)
  os::rtos::interrupts::stack ()->set (
      &_Heap_Limit,
      static_cast<size_t> (reinterpret_cast<char*> (&__stack)
                           - reinterpret_cast<char*> (&_Heap_Limit)));
#endif /* defined(OS_HAS_INTERRUPTS_STACK) */
 
  // Call the main entry point, and save the exit code.
  int code = main (argc, argv);
 
  // Standard program termination;
  // `atexit()` and C++ static destructors are executed.
  exit (code);
  /* NOTREACHED */
}

References __bss_end__, __bss_start__, __stack, _edata, _Heap_Begin, _Heap_Limit, _sdata, _sidata, exit(), main(), os_initialize_bss(), os_initialize_data(), os_run_init_array(), os_startup_initialize_args(), os_startup_initialize_free_store(), os_startup_initialize_hardware(), os_startup_initialize_hardware_early(), os::rtos::thread::stack::set(), os::rtos::interrupts::stack(), trace_initialize(), trace_printf(), and trace_puts().

os_rtos_application_out_of_memory_hook()

void os_rtos_application_out_of_memory_hook

(

void

)

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.

{
  estd::__throw_bad_alloc ();
}

References os::estd::__throw_bad_alloc().

Referenced by os_startup_initialize_free_store().

os_rtos_idle_enter_power_saving_mode_hook()

bool os_rtos_idle_enter_power_saving_mode_hook

(

void

)

Parameters

None.

Return values

true	The hook entered a power saving mode.
false	The 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 57 of file os-idle.cpp.

{
  return false;
}

Referenced by os_rtos_idle_actions().

os_rtos_system_out_of_memory_hook()

void os_rtos_system_out_of_memory_hook

(

void

)

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.

{
  estd::__throw_bad_alloc ();
}

References os::estd::__throw_bad_alloc().

Referenced by os_startup_initialize_free_store().

os_startup_create_thread_idle()

void os_startup_create_thread_idle

(

void

)

Parameters

None.

Returns

Nothing.

Referenced by main().

os_startup_initialize_args()

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

Parameters

[out]	p_argc	Pointer to argc.
[out]	p_argv	Pointer to argv.

Definition at line 406 of file startup.cpp.

{
  // By the time we reach this, the data and bss should have been initialised.
 
  // The strings pointed to by the argv array shall be modifiable by the
  // program, and retain their last-stored values between program startup
  // and program termination. (static, no const)
  static char name[] = "";
 
  // The string pointed to by argv[0] represents the program name;
  // argv[0][0] shall be the null character if the program name is not
  // available from the host environment. argv[argc] shall be a null pointer.
  // (static, no const)
  static char* argv[2] = { name, NULL };
 
  *p_argc = 1;
  *p_argv = &argv[0];
 
  return;
}

Referenced by _start().

os_startup_initialize_free_store()

void os_startup_initialize_free_store	(	void *	heap_address,
		size_t	heap_size_bytes
	)

Parameters

heap_address	The first unallocated RAM address (after the BSS).
heap_size_bytes	The free store size.

Returns

Nothing.

Referenced by _start().

os_startup_initialize_hardware()

void os_startup_initialize_hardware

(

void

)

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 114 of file initialize-hardware.c.

{
  // Call the CSMSIS system clock routine to store the clock frequency
  // in the SystemCoreClock global RAM location.
  SystemCoreClockUpdate ();
}

Referenced by _start().

os_startup_initialize_hardware_early()

void os_startup_initialize_hardware_early

(

void

)

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 54 of file initialize-hardware.c.

{
  // Call the CSMSIS system initialisation routine.
  SystemInit ();
 
#if defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7EM__)
 
  // Set VTOR to the actual address, provided by the linker script.
  // Override the manual, possibly wrong, SystemInit() setting.
  SCB->VTOR = (uint32_t)(&__vectors_start);
  // Ensure all subsequence instructions use the new configuration.
  __DSB ();
 
#endif /* defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7EM__) */
 
  // The current version of SystemInit() leaves the value of the clock
  // in a RAM variable (SystemCoreClock), which will be cleared shortly,
  // so it needs to be recomputed after the RAM initialisations
  // are completed.
 
#if defined(OS_INCLUDE_STARTUP_INIT_FP) || defined(__ARM_FP)
 
  // Normally FP init is done by SystemInit(). In case this is not done
  // there, it is possible to force its inclusion by defining
  // OS_INCLUDE_STARTUP_INIT_FP.
 
  // Enable the Cortex-M4 FPU only when -mfloat-abi=hard or -mfloat-abi=softfp.
  // Code taken from Section 7.1, Cortex-M4 TRM (DDI0439C)
 
  // Set bits 20-23 to enable CP10 and CP11 coprocessor.
  SCB->CPACR |= (0xF << 20);
 
  // Lazy save.
  FPU->FPCCR |= FPU_FPCCR_ASPEN_Msk | FPU_FPCCR_LSPEN_Msk;
 
#endif /* defined(OS_INCLUDE_STARTUP_INIT_FP) || defined (__ARM_FP) */
 
#if defined(OS_DEBUG_SEMIHOSTING_FAULTS)
 
  SCB->SHCSR |= SCB_SHCSR_USGFAULTENA_Msk;
 
#endif
}

Referenced by _start().

os_terminate()

void os_terminate

(

int

code

)

Parameters

[in]

code

Exit code, 0 for success, non 0 for failure.

Returns

Nothing.

Referenced by _Exit(), and exit().

os_terminate_goodbye()

void os_terminate_goodbye

(

void

)

Parameters

None.

Returns

Nothing.

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

{
#if defined(TRACE)
 
  trace::printf ("\n");
 
#if !defined(OS_EXCLUDE_DYNAMIC_MEMORY_ALLOCATIONS)
 
  // Application memory.
  estd::pmr::get_default_resource ()->trace_print_statistics ();
 
#if defined(OS_INTEGER_RTOS_DYNAMIC_MEMORY_SIZE_BYTES)
  rtos::memory::get_default_resource ()->trace_print_statistics ();
#endif /* defined(OS_INTEGER_RTOS_DYNAMIC_MEMORY_SIZE_BYTES) */
 
#endif /* !defined(OS_EXCLUDE_DYNAMIC_MEMORY_ALLOCATIONS) */
 
  class rtos::thread::stack& st = os_main_thread->stack ();
 
  trace::printf ("Main thread stack: %u/%u bytes used\n",
                 st.size () - st.available (), st.size ());
 
#if defined(OS_HAS_INTERRUPTS_STACK)
  trace::printf ("Interrupts stack: %u/%u bytes used\n",
                 rtos::interrupts::stack ()->size ()
                     - rtos::interrupts::stack ()->available (),
                 rtos::interrupts::stack ()->size ());
#endif /* defined(OS_HAS_INTERRUPTS_STACK) */
 
  trace::printf ("\nHasta la Vista!\n");
 
#endif /* defined(TRACE) */
}

References os::rtos::thread::stack::available(), os::estd::pmr::get_default_resource(), os::rtos::memory::get_default_resource(), os_main_thread, os::trace::printf(), os::rtos::thread::stack::size(), os::rtos::thread::stack(), os::rtos::interrupts::stack(), and os::rtos::memory::memory_resource::trace_print_statistics().

Referenced by _Exit().