...
As you will see, you can start with the template files provided with µC/CPU and µC/OS-III with little or no modifications.
This is done to ensure that we only have two tasks in the test application, OS_IdleTask() and OS_TickTask().
...
| Code Block |
|---|
...
Verifying Task Context Switches
In this section, we will verify the proper operation of the following functions/macros:
...
| ||
\Micrium \Software \EvalBoards |
...
\MyBoardManufacturer |
...
|
...
\MyBoardName |
...
|
...
\MyToolsName |
...
|
...
|
...
|
...
Our first test is to verify that µC/OS-III gets properly initialized and that the code in OSTaskStkInit() properly initializes a task’s stack.
Recall that our application consist of app.c which contains the code shown below:
| Code Block |
|---|
\MyBSP /* app.c */ #include "os.h" bsp.c #include "app_cfg.h" static OS_TCB bsp.h App_TaskStartTCB; static CPU_STK_SIZE App_TaskStartStk[APP_CFG_TASK_START_STK_SIZE]; bsp_os.c static void App_TaskStart(void *p_arg); <- See the section voidµC/OS-III port main (void) { bsp_os_a.asm (optional) <- See the OS_ERR err;section µC/OS-III port OSInit(&err);bsp_os.h OSTaskCreate(&App_TaskStartTCB, <- See the section µC/OS-III port cpu_bsp.c "App Task Start", cpu_bsp.h App_TaskStart, \MyTest (1) 0, app.c (2) APP_CFG_TASK_START_PRIO,app_cfg.h (3) cpu_cfg.h &App_TaskStartStk[0], (4) <- Copied from \Micrium\Software\uC-CPU\Cfg\Template (APP_CFG_TASK_START_STK_SIZE / 10u),lib_cfg.h <- Copied from \Micrium\Software\uC-LIB\Cfg\Template APPos_CFG_TASK_START_STK_SIZE,app_hooks.c <- Copied from \Micrium\Software\uCOS-III\Cfg\Template 0, os_app_hooks.h <- Copied from \Micrium\Software\uCOS-III\Cfg\Template 0, os_cfg.h (5) <- Copied from \Micrium\Software\uCOS-III\Cfg\Template 0, os_cfg_app.h <- Copied from \Micrium\Software\uCOS-III\Cfg\Template (OS_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR),os_type.h <- Copied from \Micrium\Software\uCOS-III\Source \Micrium \Software \uC-CPU &err); cpu_core.c cpu_core.h OSStart(&err); cpu_def.h \MyCPUName } static void App_TaskStart (void *p_arg) \MyToolsName { OS_ERRcpu.h err; OSTaskSuspend(0, &err); <- See the section µC/CPU } |
STEP 1
You now need to build and download this project to your target. Building is obviously highly toolchain specific. Of course, if you encounter errors during the build, you will need to resolve those before being able to move to the next step.
Once all build errors have been resolved, you need to download the target code onto the evaluation board you selected for the tests.
STEP 2
You then need to set a breakpoint at the OSStart() line. In other words, have your target stop AFTER executing OSInit(). You should then examine the contents of ‘err’ and confirm that it has the value OS_ERR_NONE (or, 0). If you get anything other than OS_ERR_NONE, the error code will tell you where the problem is (see section A-20).
STEP 3
If err is OS_ERR_NONE then you can ‘Step Into’ OSStart() (file os_core.c). You should see the following code:
| Code Block |
|---|
void OSStart (OS_ERR *p_err) { cpu_a.asm <- See the section µC/CPU \Micrium \Software \uC-LIB lib_ascii.c lib_ascii.h lib_def.h lib_math.c lib_math.h lib_mem.c lib_mem.h lib_str.c lib_str.h \Micrium \Software \uC/OS-III \Cfg os_app_hooks.c #ifdef OSos_SAFETYapp_CRITICALhooks.h os_cfg.h if (p_err == (OS_ERR *)0) { os_cfg_app.h \Ports \MyCPUName OS_SAFETY_CRITICAL_EXCEPTION(); \MyToolsName os_cpu.h return; }<- See the section µC/OS-III port #endif os_cpu_a.asm : <- See the section µC/OS-III port : os_cpu_a.inc if (OSTaskQty <= kernel_task_cnt) { - See the section µC/OS-III port os_cpu_c.c /* No application task created <- See the section µC/OS-III port \Source os.h */ os_cfg_app.c os_core.c *p_err = OS_ERR_OS_NO_APP_TASK; os_dbg.c os_flag.c return; os_mem.c os_msg.c } os_mutex.c if (OSRunning == OS_STATE_OS_STOPPED) {os_prio.c os_q.c OSPrioHighRdy = OS_PrioGetHighest();os_sem.c os_stat.c os_task.c (1) os_tick.c os_time.c OSPrioCur = OSPrioHighRdy;os_tmr.c os_trace.c os_type.h OSTCBHighRdyPtr = OSRdyList[OSPrioHighRdy].HeadPtr;os_var.c |
| Panel | ||
|---|---|---|
| ||
(1) (2) |
| Code Block | ||
|---|---|---|
| ||
/* app.c */ (2) #include <os.h> OSTCBCurPtr #include = OSTCBHighRdyPtr;"app_cfg.h" static OS_TCB OSRunning App_TaskStartTCB; = OS_STATE_OS_RUNNING; static CPU_STK_SIZE App_TaskStartStk[APP_CFG_TASK_START_STK_SIZE]; OSStartHighRdy();static void App_TaskStart(void *p_arg); void main (void) { (3) OS_ERR err; *p_err = OS_ERR_FATAL_RETURN OSInit(&err); OSTaskCreate(&App_TaskStartTCB, } else { "App Task Start", *p_errApp_TaskStart, = OS_ERR_OS_RUNNING; 0, } } |
STEP 4
...
APP_CFG_ |
...
TASK_ |
...
STEP 5
Now, ‘Step Into’ OSStartHighRdy() (file os_cpu_a.asm). You should see the assembly language shown below.
| Code Block |
|---|
START_PRIO, OSStartHighRdy: &App_TaskStartStk[0], OSTaskSwHook(); SP = OSTCBHighRdyPtr->StkPtr; (APP_CFG_TASK_START_STK_SIZE / 10u), OS_CTX_RESTORE Return from Interrupt/Exception; |
You can ‘Step Over’ OSTaskSwHook() and the code to load the stack pointer. However, you should set a breakpoint at the ‘Return from Interrupt/Exception’ instruction. Once you executed the OS_CTX_RESTORE macro, you should look at the CPU registers and confirm that they all have their expected value (0x12121212 for R12, 0x05050505 for R5, etc.). If not then something is not quite right with either OSTaskStkInit() or the OS_CTX_RESTORE macro. Basically, OSTaskStkInit() sets up the stack and OS_CTX_RESTORE sets up the registers based on what’s on the stack.
STEP 6
If the CPU registers appear to have their proper value then you can ‘Single Step’ and execute the ‘Return from Interrupt/Exception’ instruction. If all is well, you should be looking at the OS_TickTask() code which should look something like this:
| Code Block |
|---|
APP_CFG_TASK_START_STK_SIZE, 0, 0, void OS_TickTask (void *p_arg) 0, { (OS_ERR err;_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR), CPU_TS ts; &err); OSStart(&err); } p_arg = p_arg; static void App_TaskStart (void *p_arg) { OS_ERR err; while (DEF_ON) { OSTaskSuspend(0, &err); (void)OSTaskSemPend((OS_TICK )0, (OS_OPT )OS_OPT_PEND_BLOCKING, (CPU_TS *)&ts, (OS_ERR *)&err); if (err == OS_ERR_NONE) { <- Set a BREAKPOINT here! if (OSRunning == OS_STATE_OS_RUNNING) { OS_TickListUpdate(); } |
| Panel | ||
|---|---|---|
| ||
(3) APP_CFG_TASK_START_PRIO 2u (4) The remaining files are copied from the directories shown in the listing at the top of this page, and should not be changed at this point. (5) You need to edit
|
This is done to ensure that we only have two tasks in the test application, OS_IdleTask() and OS_TickTask().
For this test, you need to add one line of code in OSIdleTaskHook() as shown below. Once we verify OSInit(), OSTaskStkInit(), OSCtxSw(), OS_CTX_SAVE and OS_CTX_RESTORE, we’ll remove this code:
| Code Block | ||
|---|---|---|
| ||
void OSIdleTaskHook (void) } { } OSTimeTick(); #if OS_CFG_APP_HOOKS_EN > }0u } |
If the debugger doesn’t show you this code then it’s possible that the PC and PSW are not properly setup on the task stack by OSTaskStkInit().
If you end up in OS_TickTask() your code for OSTaskStkInit() and the macro OS_CTX_RESTORE is correct.
You should now set a breakpoint on the line following OSTaskSemPend().
STEP 7
You need to set another breakpoint in OSCtxSw() as shown below.
| Code Block |
|---|
if (OS_AppIdleTaskHookPtr != (OS_APP_HOOK_VOID)0) { OSCtxSw: (*OS_AppIdleTaskHookPtr)(); } #endif } |
Verifying Task Context Switches
In this section, we will verify the proper operation of the following functions/macros:
OSInit()
...
...
...
...
...
(os_core.c)
OSStartHighRdy() (os_cpu_a.asm)
OSTaskStkInit()
...
(os_
...
cpu_c.c)OSCtxSw()
...
(os_cpu_a.asm)OS_CTX_SAVE
...
...
...
(os_cpu_a.inc)
OS_CTX_RESTORE
...
(os_cpu_a.inc)CPU_SR_Save()
...
(cpu_a.asm)
CPU_SR_Restore()
...
(cpu_a.asm) Our first test is to verify that µC/OS-III gets properly initialized and that the code in OSTaskStkInit() properly initializes a task’s stack.
Recall that our application consist of app.c which contains the code shown below:
| Code Block |
|---|
/* app.c */ OSTCBCurPtr = OSTCBHighRdyPtr; #include "os.h" SP #include "app_cfg.h" = OSTCBCurPtr->StkPtr; static OS_TCB OS_CTX_RESTORE App_TaskStartTCB; static Return from Interrupt/Exception; |
You can now run the code at full speed. Because of the breakpoint in OSCtxSw(), the debugger should stop and show you the code for OSCtxSw().
Basically, what’s happening here is that OS_TickTask() will be waiting for the tick ISR to signal the task that a tick has expired. Since we haven’t setup the tick interrupt (not yet anyway), OS_TickTask() would never get to execute. However, I had you modify the idle task hook to simulate signaling the tick task so µC/OS-III will eventually switch back to this code. In the meantime, µC/OS-III will switch to the next task that’s ready-to-run. This happens to be the idle task. We’ll be following the code until we get to OS_IdleTask().
STEP 8
You can ‘Step Over’ OS_CTX_SAVE and verify that the stack (pointed to by SP) contains the value of the CPU registers saved in the same order as they are in OSTaskStkInit(). In fact, you can verify this when context switches back out of the idle task in just a few more steps.
STEP 9
‘Step Into’ the code one more time and verify that the SP was saved in OSTickTaskTCB.StkPtr.
STEP 10
‘Step Into’ the code and stop just before executing the ‘Return from Interrupt/Exception’ instruction. At this point, the CPU registers should contain the proper register values (similar to what we had when we restored the CPU registers for OSTickTask() (but this time it’s for OS_IdleTask()).
STEP 11
...
CPU_STK_SIZE App_TaskStartStk[APP_CFG_TASK_START_STK_SIZE];
static void App_TaskStart(void *p_arg);
void main (void)
{
OS_ERR err;
OSInit(&err);
OSTaskCreate(&App_TaskStartTCB,
"App Task Start",
App_TaskStart,
0,
APP_CFG_TASK_START_PRIO,
&App_TaskStartStk[0],
(APP_CFG_TASK_START_STK_SIZE / 10u),
APP_CFG_TASK_START_STK_SIZE,
0,
0,
0,
(OS_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR),
&err);
OSStart(&err);
}
static void App_TaskStart (void *p_arg)
{
OS_ERR err;
OSTaskSuspend(0, &err);
}
|
STEP 1
You now need to build and download this project to your target. Building is obviously highly toolchain specific. Of course, if you encounter errors during the build, you will need to resolve those before being able to move to the next step.
Once all build errors have been resolved, you need to download the target code onto the evaluation board you selected for the tests.
STEP 2
You then need to set a breakpoint at the OSStart() line. In other words, have your target stop AFTER executing OSInit(). You should then examine the contents of ‘err’ and confirm that it has the value OS_ERR_NONE (or, 0). If you get anything other than OS_ERR_NONE, the error code will tell you where the problem is (see section A-20).
STEP 3
If err is OS_ERR_NONE then you can ‘Step Into’ OSStart() (file os_core.c). You should see the following code:
| Code Block |
|---|
void OSStart (OS_ERR *p_err)
{
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
:
:
if (OSTaskQty <= kernel_task_cnt) { /* No application task created */
*p_err = OS_ERR_OS_NO_APP_TASK;
return;
}
if (OSRunning == OS_STATE_OS_STOPPED) {
OSPrioHighRdy = OS_PrioGetHighest(); (1)
OSPrioCur = OSPrioHighRdy;
OSTCBHighRdyPtr = OSRdyList[OSPrioHighRdy].HeadPtr; (2)
OSTCBCurPtr = OSTCBHighRdyPtr;
OSRunning = OS_STATE_OS_RUNNING;
OSStartHighRdy(); (3)
*p_err = OS_ERR_FATAL_RETURN;
} else {
*p_err = OS_ERR_OS_RUNNING;
}
}
|
STEP 4
Step into the code and stop just before executing OSStartHighRdy(). You should confirm that OSPrioCur is the same value as OS_CFG_TICK_TASK_PRIO (see os_cfg_app.h) and that OSTCBHighRdyPtr point at OSTickTaskTCB. In other words, the highest priority task should be the tick task because we should only have two task created after OSInit() and the tick task always has a higher priority than the idle task.
STEP 5
Now, ‘Step Into’ OSStartHighRdy() (file os_cpu_a.asm). You should see the assembly language shown below.
| Code Block |
|---|
OSStartHighRdy:
OSTaskSwHook();
SP = OSTCBHighRdyPtr->StkPtr;
OS_CTX_RESTORE
Return from Interrupt/Exception;
|
You can ‘Step Over’ OSTaskSwHook() and the code to load the stack pointer. However, you should set a breakpoint at the ‘Return from Interrupt/Exception’ instruction. Once you executed the OS_CTX_RESTORE macro, you should look at the CPU registers and confirm that they all have their expected value (0x12121212 for R12, 0x05050505 for R5, etc.). If not then something is not quite right with either OSTaskStkInit() or the OS_CTX_RESTORE macro. Basically, OSTaskStkInit() sets up the stack and OS_CTX_RESTORE sets up the registers based on what’s on the stack.
STEP 6
If the CPU registers appear to have their proper value then you can ‘Single Step’ and execute the ‘Return from Interrupt/Exception’ instruction. If all is well, you should be looking at the OS_TickTask() code which should look something like this:
| Code Block |
|---|
void OS_TickTask (void *p_arg)
{
OS_ERR err;
CPU_TS ts;
p_arg = p_arg;
while (DEF_ON) {
(void)OSTaskSemPend((OS_TICK )0,
(OS_OPT )OS_OPT_PEND_BLOCKING,
(CPU_TS *)&ts,
(OS_ERR *)&err);
if (err == OS_ERR_NONE) { <- Set a BREAKPOINT here!
if (OSRunning == OS_STATE_OS_RUNNING) {
OS_TickListUpdate();
}
}
}
}
|
If the debugger doesn’t show you this code then it’s possible that the PC and PSW are not properly setup on the task stack by OSTaskStkInit().
If you end up in OS_TickTask() your code for OSTaskStkInit() and the macro OS_CTX_RESTORE is correct.
You should now set a breakpoint on the line following OSTaskSemPend().
STEP 7
You need to set another breakpoint in OSCtxSw() as shown below.
| Code Block |
|---|
OSCtxSw: <- Set a BREAKPOINT here!
OS_CTX_SAVE
OSTCBCurPtr->StkPtr = SP;
OSTaskSwHook();
OSPrioCur = OSPrioHighRdy;
OSTCBCurPtr = OSTCBHighRdyPtr;
SP = OSTCBCurPtr->StkPtr;
OS_CTX_RESTORE
Return from Interrupt/Exception;
|
You can now run the code at full speed. Because of the breakpoint in OSCtxSw(), the debugger should stop and show you the code for OSCtxSw().
Basically, what’s happening here is that OS_TickTask() will be waiting for the tick ISR to signal the task that a tick has expired. Since we haven’t setup the tick interrupt (not yet anyway), OS_TickTask() would never get to execute. However, I had you modify the idle task hook to simulate signaling the tick task so µC/OS-III will eventually switch back to this code. In the meantime, µC/OS-III will switch to the next task that’s ready-to-run. This happens to be the idle task. We’ll be following the code until we get to OS_IdleTask().
STEP 8
You can ‘Step Over’ OS_CTX_SAVE and verify that the stack (pointed to by SP) contains the value of the CPU registers saved in the same order as they are in OSTaskStkInit(). In fact, you can verify this when context switches back out of the idle task in just a few more steps.
STEP 9
‘Step Into’ the code one more time and verify that the SP was saved in OSTickTaskTCB.StkPtr.
STEP 10
‘Step Into’ the code and stop just before executing the ‘Return from Interrupt/Exception’ instruction. At this point, the CPU registers should contain the proper register values (similar to what we had when we restored the CPU registers for OSTickTask() (but this time it’s for OS_IdleTask()).
STEP 11
‘Step Into’ the return from interrupt/exception instruction and the CPU should now jump into the idle task (os_core.c) as shown below. You should then set a breakpoint as shown.
| Code Block |
|---|
void OS_IdleTask (void *p_arg)
{
CPU_SR_ALLOC();
p_arg = p_arg;
while (DEF_ON) {
CPU_CRITICAL_ENTER(); <- Set a BREAKPOINT here!
OSIdleTaskCtr++;
#if OS_CFG_STAT_TASK_EN > 0u
OSStatTaskCtr++;
#endif
CPU_CRITICAL_EXIT();
<strong> OSIdleTaskHook();</strong>
}
}
|
STEP 12
‘Step Into’ the idle task and then, ‘Step Into’ OSIdleTaskHook(). Recall that I had you modify the idle task hook as shown below. What we’re doing here is simulate the occurrence of the tick interrupt.
| Code Block |
|---|
void OS_IdleTaskOSIdleTaskHook (void *p_arg)) { <strong>OSTimeTick();</strong> {#if OS_CFG_APP_HOOKS_EN > 0u if (OS_AppIdleTaskHookPtr CPU_SR_ALLOC(); != (OS_APP_HOOK_VOID)0) { (*OS_AppIdleTaskHookPtr)(); } p_arg = p_arg; #endif while (DEF_ON) {} |
STEP 13
Have your debugger run the code at full speed. You should actually hit the breakpoint in OSCtxSw() as shown below. What happened here is that µC/OS-III signaled the tick task and since the tick task is more important than the idle task, µC/OS-III is switching back to the tick task.
| Code Block |
|---|
OSCtxSw: CPU_CRITICAL_ENTER(); <- Set a BREAKPOINT here! . OSIdleTaskCtr++; #if OS_CFG_STAT_TASK_EN > 0uCTX_SAVE OSStatTaskCtr++; #endif OSTCBCurPtr->StkPtr = SP; CPU_CRITICAL_EXIT(); OSTaskSwHook(); OSPrioCur = OSPrioHighRdy; <strong> OSIdleTaskHook();</strong> OSTCBCurPtr = OSTCBHighRdyPtr; } } |
STEP 12
‘Step Into’ the idle task and then, ‘Step Into’ OSIdleTaskHook(). Recall that I had you modify the idle task hook as shown below. What we’re doing here is simulate the occurrence of the tick interrupt.
STEP 13
...
SP = OSTCBCurPtr->StkPtr;
OS_CTX_RESTORE
Return from Interrupt/Exception; |
STEP 14
You can run the target at full speed and the debugger should bring you back at the breakpoint in OS_TickTask().
...
| Code Block |
|---|
/* app.c */
#include <os.h>
#include "app_cfg.h"
static OS_TCB App_TaskStartTCB;
static CPU_STK_SIZE App_TaskStartStk[APP_CFG_TASK_START_STK_SIZE];
static void App_TaskStart(void *p_arg);
void main (void)
{
OS_ERR err;
OSInit(&err);
/* (1) Install interrupt vector for OSTickISR() */
/* (2) Initialize the tick timer to generate interrupts every millisecond */
OSTaskCreate(&App_TaskStartTCB,
"App Task Start",
App_TaskStart,
0,
APP_CFG_TASK_START_PRIO,
&App_TaskStartStk[0],
(APP_CFG_TASK_START_STK_SIZE / 10u),
APP_CFG_TASK_START_STK_SIZE,
0,
0,
0,
(OS_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR),
&err);
CPU_INT_EN(); /* (3) Enable interrupts */
OSStart(&err);
}
static void App_TaskStart (void *p_arg)
{
OS_ERR err;
OSTaskSuspend(0, &err);
OS_ERR err;
OSTaskSuspend(0, &err);
}} |
| Panel | ||
|---|---|---|
| ||
(1) You need to setup the interrupt vector for the tick ISR. Where this is done greatly depends on the CPU architecture. On some processors, you would simply insert a pointer to (2) You can setup the timer you will use to generate interrupts here. You need to make sure that the interrupt will not occur immediately but instead 1 millisecond after the timer is initialized. You may recall that I told you to always initialize the tick interrupt from the first task that executes when we start multitasking. However, since we are testing the port, it’s safe to initialize the timer here since we have control over when the first interrupt will actually occur. (3) This macro is used to enable global CPU interrupts. It’s assumed that the startup code runs with interrupts disabled and thus, those need to be explicitly enabled. |
At this point, you need to remove all breakpoints you inserted to test the task level context switch code and insert the following breakpoints. You should note that the C-like code should actually be replaced with assembly language instructions for your processor.
...