OSRedzoneHitHook

Description

OSRedzoneHitHook() is a function called by µC/OS-III’s Task Switching Hook, OSTaskSwHook(). The hook is called when µC/OS-III determines that the task to be switched out has overflowed its stack. The hook can then cleanly exit the application, report an error, try to fix the stack or simply call the software based exception, CPU_SW_EXCEPTION(). The hook, if defined, must ultimately call CPU_SW_EXCEPTION() or stop µC/OS-III from executing a corrupted task.

Files

os.h/os_cpu_c.c and os_app_hooks.c

Prototype

void  OSRedzoneHitHook (OS_TCB  *p_tcb)

Arguments

p_tcb

is a pointer to the TCB of the offending task. Note that p_tcb can be NULL. In that case, the ISR stack is corrupted.

Returned Values

None

Required Configuration

OS_CFG_APP_HOOKS_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

OSRedzoneHitHook() through OSIntExit() and OSTaskSwHook().

Notes/Warnings

1. If the application hook is defined, it must stop µC/OS-III from executing a corrupted task by, for example, calling the software based exception, CPU_SW_EXCEPTION().

Example Usage

The code below calls an application-specific hook that an application programmer can define. For this, the user can simply set the value of OS_AppRedzoneHitHookPtr to point to the desired hook function (see App_OS_SetAllHooks() in os_app_hooks.c).

In the example below, OSRedzoneHitHook() calls App_OS_RedzoneHitHook() if the pointer OS_AppRedzoneHitHookPtr is set to that function.

          void  App_OS_RedzoneHitHook (OS_TCB  *p_tcb)                  /* os_app_hooks.c        */
          {
              (void)&p_tcb;
              CPU_SW_EXCEPTION(;);
          }
           
           
          void  App_OS_SetAllHooks (void)                            /* os_app_hooks.c        */
          {
              CPU_SR_ALLOC();
           
              CPU_CRITICAL_ENTER();
              :
              OS_AppRedzoneHitHookPtr = App_OS_RedzoneHitHook;
              :
              CPU_CRITICAL_EXIT();
          }
           
 
          void  OSRedzoneHitHook (OS_TCB  *p_tcb)                    /* os_cpu_c.c            */
          {
          #if OS_CFG_APP_HOOKS_EN > 0u
              if (OS_AppRedzoneHitHookPtr != (OS_APP_HOOK_TCB)0) {
                  (*OS_AppRedzoneHitHookPtr)(p_tcb);
              }
          #endif
              (void)p_tcb;
              CPU_SW_EXCEPTION(;);
          }