{"id":4398,"date":"2018-11-19T16:22:31","date_gmt":"2018-11-20T00:22:31","guid":{"rendered":"https:\/\/visualgdb.com\/w\/?p=4398"},"modified":"2018-11-19T17:04:29","modified_gmt":"2018-11-20T01:04:29","slug":"tracing-the-real-time-events-in-rtx-based-projects-with-real-time-watch","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/arm\/keil\/rtx\/tracing\/","title":{"rendered":"Tracing the Real-Time Events in RTX-based Projects with Real-Time Watch"},"content":{"rendered":"

This tutorial shows how to use the real-time watch feature of VisualGDB to trace the thread and function run times as well as the mutex and queue use\u00a0for\u00a0projects based on the RTX operating system. We will\u00a0create a\u00a0basic project using the Keil compiler, add the RTX5 pack to it and will show how to\u00a0use real-time watch to trace various events in it.<\/p>\n

Before you begin, install VisualGDB 5.4 Preview 10 or later and create a basic “Blinking LED” project\u00a0using the RTX operating system by following this tutorial<\/a>.<\/p>\n

    \n
  1. Open\u00a0VisualGDB Project Propertes for your project and go to the Embedded Frameworks page. Then reference the “Fast Semihosting and Embedded Profiler” framework:\"01-framework\"<\/a>As configuring the sampling profiler under the Keil compiler requires extra steps,\u00a0select “Exclude sampling profiler code” in the framework configuration. Also set RTOS support to “Keil RTX”.<\/li>\n
  2. Include the <SysprogsProfiler.h><\/strong> file from your main() function and call InitializeInstrumentingProfiler() after you\u00a0set the system clock frequency:
    \n    \"02-init\"<\/a><\/li>\n
  3. Open VisualGDB Project Properties again, go to the Dynamic\u00a0Analysis page and enable\u00a0tracing of RTOS events and function calls.\u00a0If the project is not configured to generate relocation records,\u00a0click on the link at the bottom of the page to automatically enable them:\"03-profile\"<\/a><\/li>\n
  4. Build the project and start debugging it. If\u00a0you are using a version of RTX that does not include a\u00a0low-level thread switch hook, the debugging will fail\u00a0complaining about the missing thread_switch_helper()<\/strong> function:\"04-fail\"<\/a><\/li>\n
  5. In order to fix it, locate the\u00a0RTX interrupt handler file (e.g. irq_cm4f.s) and find the SVC_ContextSwitch label. Add the following code after the “STR R2,[R3]” instruction:\n
    PUSH {R2,R3} ; Save registers\r\nbl thread_switch_helper\r\nPOP {R2,R3} ; Restore registers<\/pre>\n
    Also add the “IMPORT thread_switch_helper” statement\u00a0after the “IMPORT osRtxInfo” statement in the beginning of the SVC_Handler call:\"05-helper\"<\/a>Finally, add an empty thread_switch_helper() function in one of your source files (don’t forget to mark it with extern “C” if you are using C++):<\/p>\n
    void thread_switch_helper()\r\n{\r\n}<\/pre>\n
    When you start\u00a0a profiling or real-time watch session with VisualGDB, the\u00a0it will hook the\u00a0thread_switch_helper()<\/strong> function\u00a0redirecting it to\u00a0SysprogsRTOSHooks_RTX_thread_switch_helper()<\/strong>, that will\u00a0allow the profiler\u00a0framework to\u00a0maintain separate contexts for each of the RTOS threads. Hooking the low-level thread_switch_helper()<\/strong> instead\u00a0using a higher-level\u00a0EvtRtxThreadSwitched()<\/strong> callback allows instrumenting not only the user-mode code, but the RTX functions\u00a0related to the high-level thread switching logic.<\/li>\n
  6. Press F5 to begin debugging. Set a breakpoint in one of the threads and wait for it to trigger. Then open the real-time watch window and enable the “Show RTOS threads” checkbox. Once you resume the program, VisualGDB will visualize the run times of your threads.\u00a0In this example, thread #1 runs twice more frequently than thread #2 as it uses twice shorter sleep delays:
    \n    \"06-rtw\"<\/a><\/li>\n
  7. Add the LED_On()<\/strong> and LED_Off()<\/strong> functions to the real-time watch:\"07-led\"<\/a><\/li>\n
  8. If you try resuming the session now, the program will fail with the “Stack underflow” condition:\"08-stack\"<\/a><\/li>\n
  9. This happens because the default RTX stack size is too small for the VisualGDB’s\u00a0profiler framework functions\u00a0in the debug configuration (with no optimization). You can fix this by\u00a0adding “.stack_size = 4096” to the thread attributes of both threads.\u00a0However, if you try running this version of the program, you will observe that the 2 user threads were never created:\"09-nothread\"<\/a><\/li>\n
  10. This happens because the default RTX dynamic memory size it too small. You can increase it by adding “OS_DYNAMIC_MEM_SIZE=16384” to the preprocessor definitions:
    \n    \"10-memsize\"<\/a><\/li>\n
  11. Note how this increases the size of the os_mem<\/strong> variable by 12KB:\"11-delta\"<\/a><\/li>\n
  12. Now you can run the\u00a0program and see the timing diagram for the LED_On() and LED_Off() functions\u00a0along with the thread times:\"12-onoff\"<\/a><\/li>\n
  13. Now we will show how to track the ownership of RTX mutexes with real-time watch. Add the following code to your project:\n
    osMutexId_t g_Mutex;\r\n\r\nvoid ExclusiveWait(int delay)\r\n{\r\n    osMutexAcquire(g_Mutex, osWaitForever);\r\n    osDelay(delay);\r\n    osMutexRelease(g_Mutex);\r\n}\r\n\r\n\/\/...\r\n\r\nint main(void)\r\n{\r\n    \/\/...\r\n    osMutexAttr_t mutexAttr = { .name = \"TestMutex\" };\r\n    g_Mutex = osMutexNew(&mutexAttr);\r\n}\r\n\r\n<\/pre>\n
    Then change the thread functions to call ExclusiveWait() instead of osDelay(). This will ensure that\u00a0only one thread at a time will be able to call ExclusiveWait(), so the wait times of the threads will be added.<\/li>\n
  14. Start debugging and add g_Mutex to the real-time watch window:
    \n<\/a>     \"14-mutex\"<\/a><\/li>\n
  15. Let the program run for a few\u00a0seconds and observe the real-time watch.\u00a0Note how the two threads take turns in owning the mutex:\"15-mutextimes\"<\/a><\/li>\n
  16. Finally, we will demonstrate\u00a0the use of a semaphore. Change the code in your main file as shown below:\n
    osSemaphoreId_t g_Semaphore;\r\n\r\nvoid ExclusiveWait(int delay)\r\n{\r\n    osMutexAcquire(g_Mutex, osWaitForever);\r\n    osDelay(delay);\r\n    osMutexRelease(g_Mutex);\r\n}\r\n\r\nvoid Thread1Body(void *argument)\r\n{\r\n    for (;;)\r\n    {\r\n        osSemaphoreAcquire(g_Semaphore, osWaitForever);\r\n        osDelay(10);\r\n    }\r\n}\r\n\r\nvoid Thread2Body(void *argument)\r\n{\r\n    for (;;)\r\n    {\r\n        for (int i = 0; i < 10; i++)\r\n            osSemaphoreRelease(g_Semaphore);\r\n        osDelay(200);\r\n    }\r\n}\r\n\r\nint main(void)\r\n{\r\n    osSemaphoreAttr_t semaphoreAttr = { .name = \"TestSemaphore\" };\r\n    g_Semaphore = osSemaphoreNew(1000, 0, &semaphoreAttr);\r\n    \/\/..\r\n}\r\n<\/pre>\n
    This will demonstrate a very basic producer\/consumer\u00a0scenario where thread #1 quickly produces 10 tokens and waits for a long time while thread #1 is consistently consuming the tokens at a slower rate.<\/li>\n
  17. Start debugging and\u00a0add g_Semaphore<\/strong> to real-time watch. Observe how the semaphore value quickly reaches the maximum and then slowly decreases as thread #1 keeps on\u00a0consuming the tokens:
    \n    \"16-semaphoretiming\"<\/a><\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"
    This tutorial shows how to use the real-time watch feature of VisualGDB to trace the thread and function run times<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[27],"tags":[53,147,175],"_links":{"self":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/4398"}],"collection":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/comments?post=4398"}],"version-history":[{"count":2,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/4398\/revisions"}],"predecessor-version":[{"id":4416,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/4398\/revisions\/4416"}],"wp:attachment":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media?parent=4398"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/categories?post=4398"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/tags?post=4398"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}