ST40 Micro Toolset user trace support
Contents
1. Building file main c Invoking ST40 C Compiler sh4gcc D__mb680sti7105__ 00 g Wall c fmessage length 0 mboard mb680sti7105 mruntime os21 ml trace trace api MMD MP MF main d MT main d o main o Main Finished building main c Building file myapp wrap c Invoking ST40 C Compiler sh4gcc D__mb680sti7105__ I 00 fno zero initialized in bss g Wall c fmessage length 0 mboard mb680sti7105 mruntime os21 ml MMD MP MF myapp wrap d MT myapp wrap d o myapp wrap o myapp wrap c myapp wrap c 8 17 warning led h No such file or directory myapp wrap c In function user_api_set_group_custom_class_enable myapp wrap c 38 warning enumeration value user_api_group_custom_class_EOF handled in switch myapp wrap c In function user_api_set_group_enable myapp wrap c 54 warning enumeration value user_api_group_EOF not handled in switch Finished building myapp wrap c Building target led out Invoking ST40 C Linker sh4gcc W1 myapp wrap 1d mboard mb680sti7105 mruntime o0s21 ml trace trace api o led out led o main o myapp wrap o Finished building target led out This is the output seen in STWorkbench s console window If you are not using STWorkbench to build the example then these commands can be entered in a command console directly or can be used to write a user supplied makefile lt 8 19 Doc ID 822. SZA Application note ST40 Micro Toolset user trace support Introduction As well as supporting the tracing of OS21 kernel activity and OS21 APIs the ST40 Micro Toolset also supports tracing for user defined APIs and activities These can all be viewed graphically using STWorkbench Figure 1 shows an example of a trace in which the mouse pointer is over a recorded call to a user API called led_on Figure 1 Captured trace displayed graphically in STWorkbench lt j led out 2010 01 26_05 01 55 3 DYKKER ja e E Z Interrupts gt timeoutHandler 0x8c00d1c TE V Tasks Idle Task 0x8c23ce28 Root Task 0x8c0224d0 A TAE 1 000 050 1 000 100 1 000 150 Time Unit microsecond Active Page 1 1 Time under cursor 34 Support for tracing user defined APIs and activities was first introduced in the ST40 Micro Toolset R5 0 0 STMicroelectronics recommend that users use the latest STWorkbench release with the ST40 Micro Toolset This application note gives a brief guide to using this facility through a worked example It also describes how this feature can be used in STAPI SDK to trace calls to the STAPI SDK API and events April 2010 Doc ID 8254555 Rev A 1 19 www st com Contents ST40 toolset user trace support Contents lntrod ction Si a enh tr vn cw ms nt ma Eo na de am a ar ee a a Be 1 1 Example of performing a user API trace 00 00 e eee eens 3 1 1 OVEIVIOW oca
3. fe C C Local Application E A ST Applications OTargetPack GDB Script 7 1200 Target Applicatio B S 140 Target Application ST SDK_Build HDK7111 ST DETO connoc 4 ST Multi launcher E Common GDB Command HDK7111_tp Connection Command HDK7111_tp GDB Debugger sh4adb i Browse GDB command fie tapisdk stapp platformhdk7111 7111 hdk7111_7111_start_scrpt cmd Warning Some commands in this file may interfere with the startup operation of the debugger For example yun lt Filter matched 5 of 4 items Apply Revert Close Doc ID 8254555 Rev A ST40 toolset user trace support User API trace and events in STAPI SDK After launching the STWorkbench debugger start a trace on the application by clicking on the Start New Analysis icon found in the Debug window This opens the Start System Analysis window as shown in Figure 15 Figure 15 Start System Analysis Window 7 Start System Analysis 0521 Profiler Le Events to record Data to record Advanced Add user defined tracepoints GDB command script file is Sy STMC Sampling C play4 practicals stapisdk stappluserapi cmd Load GDB command script file Dtistory Available tracepoints C Profiler 5 USER API STAPI t O Trace Trace instrumented USER API STEVT E calnotiry E LJ init_term notify E open_close register subscribe unsubscribe USER API STOS E cet LJ Interrupt Memory MessageQueu
4. PRINT Switching off LED led_on O 0 task_delay time ticks _per_ sec This application note describes how to trace calls to the function 1ed_on In addition the example shows a call to a function 0S21_TRACE_PRINT which prints a string into the trace buffer User trace definition file To trace an application for OS21 kernel activity OS21 APIs or both instrumented versions of the OS21 libraries must be linked with the application The same principles are also true for tracing user defined APIs and activities The first step is to write a user trace definition file specifying the APIs and events to be traced The Perl script os21usertrace uses this file to generate all the output files required to build a version of the application that is instrumented for tracing user APIs Doc ID 8254555 Rev A 3 19 Example of performing a user API trace ST40 toolset user trace support Note 4 19 In Figure 3 the trace definition file myapp def describes the function to trace led_on Figure 3 Example user trace definition file ic main c gt myapp def 3 USER INCLUDE led h USER API custom led led_on void int d finta The definition of 1ed_on indicates that the function has a return type of void and accepts two parameters both of which are 32 bit double word integers as indicated by int d See the OS21 Trace chapter in the ST40 Micro Toolset user manual 7379953 for more
5. variable When this make variable is set it prepares the STAPI SDK application so that a subset of STAPI SDK API and events can be traced The framework of this example can be customized by the user to extend or reduce the number of STAPI SDK API and events that can be traced Installing the example The example providing the 0S21_TRACEUSER make variable in STAPI SDK is available on request by contacting your FAE or ST customer contact To apply the example simply unpack it over the top of the STAPI SDK installation A readme txt file is also unpacked at the top directory and this explains which STAPI SDK files have been modified and which files have been added If the O0S21_TRACEUSER make variable is not set then STAPI SDK can be built and will run as normal There are no side effects to the normal behavior of STAPI SDK after this example has been applied Building STAPI SDK for user API trace and events As standard STAPI SDK already provides the make variables listed in Table 7 to allow the STAPI SDK application to be profiled using the OS21 Profiler and traced for OS21 events task creation interrupt handler installed context switch and so forth and OS21 API calls Table 1 Default Make variables in STAPI SDK Make variable Description O0S21_TRACE Link the application with the trace option to enable OS21 trace support Link the application with the trace trace api OS21_TRACEAPI trace api no time options t
6. 54555 Rev A ST40 toolset user trace support Example of performing a user API trace 1 5 Tracing the application When the application has been built it can then be debugged and traced with the STWorkbench debugger When the STWorkbench debugger has been launched start a trace on the application by clicking the Start New Analysis icon found in the Debug window This opens the Start System Analysis window see Figure 8 Figure 8 Start System Analysis window Start System Analysis 0521 Profiler _ _ _ Events to record Data to record Advanced Add user defined tracepoints GDB command script file is es STMC Sampling Criplayilediled out Debug myapp cmd Load GDB command script file History Available tracepoints Profiler a E exception Trace instrumented E general 7 0521 Activity Ea a E task E 0521 API USER API custom ted led_on Restore Defaults Apply Note according to your preferences profiling views are not updated automatically lt Doc ID 8254555 Rev A 9 19 Example of performing a user API trace ST40 toolset user trace support In this window you can select which OS21 kernel activity events and which OS21 APIs to record To include user defined API in the trace the GDB command script file generated by the Perl script os21usertrace must be loaded This is done by clicking on the button Load GDB command script file and selecting the appr
7. Binary Parsers Error Parsers C C General Project References Refactoring History Run Debug Settings os21usertrace d myapp in g myapp cmd I myapp wrap ld s myapp wrap c myapp def Pre build steps Command Description Post build steps Command Description Restore Defaults Apply Apply to children OK Cancel Note Windows requires double quotes around the invocation of the os21usertrace tool as shown in Figure 4 On Linux the double quotes are not required lt Doc ID 8254555 Rev A 5 19 Example of performing a user API trace ST40 toolset user trace support 1 3 Compiling the application The application can be compiled as normal with the exception of the generated source file myapp wrap c the file that wraps the function led_on to provide the necessary instrumentation This source file must be compiled with the optimization option fno zero initialized in bss which ensures that control data is initialized at the point when the application is loaded into memory This is set up in STWorkbench by specifying the option in the Properties for this source file as shown in Figure 5 Figure 5 Source File Properties window 7 Properties for myapp wrap c type filter text Settings Resource C C Build Discovery Options Configuration Debug b Manage Configurations Settings Cl Set Active Configuration Tool Chain Editor C C General Run Debug Setti
8. Task 0x8c0224d0 Ox00000000 ox00000000 2 000 196 2 000 199 3 Root Task 0x8c0224d0 ox00000001 0x00000000 3 000 243 3 000 245 2 Root Task 0x8c0224d0 0x00000000 0x00000000 4 000 289 4 000 292 3 Root Task 0x8c0224d0 ox00000001 ox00000000 Ls J lt 10 19 Doc ID 8254555 Rev A ST40 toolset user trace support Example of performing a user API trace Finally calls to the function 0S21_TRACE_PRINT which prints a user defined string into the trace buffer are highlighted using a yellow flag See Figure 12 for an example Figure 12 Calls to OS21_TRACE_PRINT highlighted with a yellow flag Sj Med out 2010 01 26_05 01 55 2 ERa A Alr AA S Hea I i ieee Oro 7 Interrupts timeoutHandler Ox8cOOd1cc E v Tasks Idle Task 0x8c23ce28 Root Task 0x8c0224d0 him 67 mt m x Switching on LED 1 000 125 1 000 130 1 000 135 1 000 140 1 000 145 1 000 150 1 000 155 1 000 160 1 000 165 1 000 170 1 000 175 1 000 180 1 000 185 a lt II TES Saaaasq o Ii5sz222 S225 Time Unit microsecond Active Page 1 1 Time under cursor 1 000 147 lt Doc ID 8254555 Rev A 11 19 User API trace and events in STAPI SDK ST40 toolset user trace support 2 2 1 2 2 2 3 12 19 User API trace and events in STAPI SDK Overview An example written by the ST40 Micro Toolset team is available When applied to STAPI SDK v0 23 onwards it provides the 0S21_TRACEUSER make
9. e Semaphore Task E virt memcpy memset LJ time lt 0521 Activity RRA 4 t ry E P r l w P KAPKA KAPKA PKS KSPKSPKSPKSIKS Restore Defaults Apply Note according to your preferences profiling views are not updated automatically In this window select which OS21 kernel activity events and which OS21 APIs to record To include user defined API in the trace load the GDB command script file stapp userapi cmd To do this click on the button Load GDB command script file When this has been done select in Available Tracepoints which STAPI SDK API and events to record Click on OK to start tracing the application To stop gathering trace data click on the Stop Analysis button of the Debug window As soon as tracing stops STWorkbench displays the recorded trace data in a chart see Figure 16 lt Doc ID 8254555 Rev A 15 19 User API trace and events in STAPI SDK ST40 toolset user trace support Figure 16 A call to STEVT_Notify is included in the trace a BTEVT Notif Included in the trace records are calls to the sub set of STAPI SDK API and events 16 19 Doc ID 8254555 Rev A ky ST40 toolset user trace support References 3 References For in depth information on OS21 trace and User API trace features refer to the OS21 Trace chapter of the S740 Micro Toolset User Manual 7379953 A
10. f such third party products or services or any intellectual property contained therein UNLESS OTHERWISE SET FORTH IN ST S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY WITH RESPECT TO THE USE AND OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND THEIR EQUIVALENTS UNDER THE LAWS OF ANY JURISDICTION OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT UNLESS EXPRESSLY APPROVED IN WRITING BY AN AUTHORIZED ST REPRESENTATIVE ST PRODUCTS ARE NOT RECOMMENDED AUTHORIZED OR WARRANTED FOR USE IN MILITARY AIR CRAFT SPACE LIFE SAVING OR LIFE SUSTAINING APPLICATIONS NOR IN PRODUCTS OR SYSTEMS WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY DEATH OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE ST PRODUCTS WHICH ARE NOT SPECIFIED AS AUTOMOTIVE GRADE MAY ONLY BE USED IN AUTOMOTIVE APPLICATIONS AT USER S OWN RISK Resale of ST products with provisions different from the statements and or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever any liability of ST ST and the ST logo are trademarks or registered trademarks of ST in various countries Information in this document supersedes and replaces all information previously supplied The ST logo is a registered trade
11. information concerning the user trace definition file Using this file as input the Perl script os21usertrace generates the following files e aconirol file for example myapp in e aGDBcommand script file for example myapp cmd to allow calls to led_on tobe captured and viewed in STWorkbench s trace view a linker script file for example myapp wrap Id to pull in a instrumented version of led_on e a source file for example myapp wrap c that wraps the function 1ed_on to provide the necessary instrumentation Doc ID 8254555 Rev A ky ST40 toolset user trace support Example of performing a user API trace Use the following command line to process the example trace definition file myapp def of the LED example os2lusertrace d myapp in g myapp cmd 1 myapp wrap ld s myapp wrap c myapp def This command line can be invoked directly from a command console either by a user supplied makefile or by STWorkbench If processing the command using STWorkbench specify the command as a pre build step This is seen in the Project Properties window see Figure 4 Figure 4 Project properties window 7 Properties for led out type filter text Settings Resource Builders S C C Build Configuration Debug Manage Configurations Build Variables C Set Active Configuration Discovery Options Environment Settings a eer Tool Chain Editor Tool Settings Build Steps Build Artifact lon
12. lso refer to STWorkbench Help for assistance on getting started using these facilities in STWorkbench ky Doc ID 8254555 Rev A 17 19 Revision history ST40 toolset user trace support 4 18 19 Revision history Table 2 Document revision history Date Revision Changes 26 Apr 2010 A Initial release Doc ID 8254555 Rev A ST40 toolset user trace support Please Read Carefully Information in this document is provided solely in connection with ST products STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections modifications or improvements to this document and the products and services described herein at any time without notice All ST products are sold pursuant to ST s terms and conditions of sale Purchasers are solely responsible for the choice selection and use of the ST products and services described herein and ST assumes no liability whatsoever relating to the choice selection or use of the ST products and services described herein No license express or implied by estoppel or otherwise to any intellectual property rights is granted under this document If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever o
13. mark of STMicroelectronics All other names are the property of their respective owners 2010 STMicroelectronics All rights reserved STMicroelectronics group of companies Australia Belgium Brazil Canada China Czech Republic Finland France Germany Hong Kong India Israel Italy Japan Malaysia Malta Morocco Philippines Singapore Spain Sweden Switzerland United Kingdom United States of America www st com ky Doc ID 8254555 Rev A 19 19
14. n oe eee eee cea ee eee Re eee eee oe eS SRE ee 3 1 2 User trace definition file 0 000 00 e eee 3 1 3 Compiling the application 0 cee 6 1 4 Linking the application 0 0000 cee 7 1 5 Tracing the application iss erads betes teedGhe 44 dees doedeeues 9 2 User API trace and events in STAPI SDK 0 2000eeeeee 12 2 1 OVGIVIOW siniri ora ea ai oan E a a EE EN Be a e E Mice 12 2 2 Installing the patch nnaaaanaa n neuna anana nnaaa 12 2 3 Building STAPI SDK for user API trace and events 12 2 4 Tracing the STAPI SDK application aeaa 13 3 REIGENCES oii serge ie iaaa naa ea ee E EO aaa p a a is 17 4 Revision history acess inwnee ceed eaw tee wees eee see 18 2 19 Doc ID 8254555 Rev A ky ST40 toolset user trace support Example of performing a user API trace 1 1 1 2 Example of performing a user API trace Overview The following example describes how support for User API trace is set up and how the captured trace can be viewed in STWorkbench Figure 2 shows the main c of the LED example in the STWorkbench editor Figure 2 main c of the LED example main c 3 E myapp def include led h int main void O3521_ TRACE PRINT About to initialize and start 0521 kernel initialize NULL kernel start j while 1 0521 TRACE PRINT Switching on LED led_on i 0 task _delay time ticks_per_ sec O3521_ TRACE
15. ngs C Exclude resource From build amp Tool Settings Build Steps 3 5740 C Compiler Optimization Level None 00 v Preprocessor Symbols Directories amp Debugging Warnings Miscellaneous Compiler Linker Shared Settings Other optimization flags fno zero initialized in bss Restore Defaults Apply ky 6 19 Doc ID 8254555 Rev A ST40 toolset user trace support Example of performing a user API trace 1 4 lt Linking the application When the application has been compiled the next step is to link it The application is linked in the normal manner however to enable the application to be traced remember to use the trace linker option The user can also use the trace api linker option to trace calls to the OS21 API together with all OS21 kernel activity To trace the user API led_on the generated linker script file myapp wrap Id must be specified in order to link in the instrumented version of 1ed_on This is done by adding the option W1 myapp wrap 1d to the linker command line In STWorkbench this is set up in the Linker flags field of the Project Properties window as shown in Figure 6 Figure 6 Project Properties window showing the WI myapp wrap Id option A Properties for led out type filter text Settings A Resource Configuration Debug Manage Configurations A Builders C C Build Oo Set Active Configuration Build Variables Disco
16. o initialize OS21 trace support and OS21 API tracing except for the time functions Link the application with the profiler option to initialize OS21 profiler 0 21_PROFILER support The example extends this list by providing the additional 0S21_TRACEUSER make variable When building the STAPI SDK application so that a subset of STAPI SDK API and events can be traced both the make variables 0S21_TRACEUSER and 0S21_TRACE must be set The make variable 0S 21_TRACEAPI can be set to also include calls to the OS21 API in the trace Normally the STAPI SDK application is not be prepared for OS21 profiling at the same time as OS21 tracing although this is possible Doc ID 8254555 Rev A ky ST40 toolset user trace support User API trace and events in STAPI SDK 2 4 lt Use the following command line to build STAPI SDK to prepare it so that a subset of STAPI SDK API and events can be traced along with OS21 events and API calls make apilib all OS21_TRACE 1 OS21TRACEAPI 1 O0S21_TRACEUSER 1 If STAPI SDK is being built in STWorkbench then enter the following in the Build command field of the Project Properties window apilib all build_start_script_connect_st40 0S21_TRACE 1 OS21TRACEAPI 1 OS21_ TRACEUSER 1 Figure 13 Settings in the Project Properties window to build STAPI SDK A Properties for SDK_Build type filter text C C Build Reso
17. opriate file see Figure 9 Figure 9 Select GDB command script file F Select GDB command script file defining additional tracepoints GDB command script file location _C play led led out Debuag myapp cmd File System When the command script has been loaded select which User API to record Click on OK to start tracing the application To stop gathering trace data click on the Stop Analysis button in the Debug window STWorkbench immediately displays the recorded trace data in a chart see Figure 10 Figure 10 Trace data displayed in a T chart SF led out 2010 01 26_05 01 55 3 RIAA PNE Eac i V Interrupts timeoutHandler Ox8cOOd1 cc V Tasks Idle Task Ox8c23ce28 Root Task 0x8c0224d0 1 000 050 1 000 100 1 000 150 1 000 200 gt e EE Time Unit microsecond Active Page 1 1 Time under cursor 34 Included in the trace records are calls to led_on as shown under the mouse pointer in Figure 10 It is also possible to search for these calls in the accumulated raw data using the trace search facility This is selected by clicking on the relevant icon found at the top of the window Figure 11 shows example output from trace search Figure 11 Search on the gathered trace data for led_on SF led out 2010 02 04_03 05 06 4 Search 53 5 occurence s Found Start Time End Time Duration Context Argument 0 Argument 1 a ee eT RTS TOOT TOO A 1 000 149 1 000 152 3 Root
18. urce Builders C C Build Configuration HDK7111 Manage Configurations C C General Cl Set Active Configuration Project References Run Debug Settings Builder settings Behaviour Build settings E Stop on first build error Use parallel build Workbench Build Behavior Workbench build type Make build target Build on resource save Auto build Note See Workbench automatic build preference Z Build Incremental build _st40 0521_TRACE 1 0521_TRACEAPI 1 0521_TRACEUSER 1 Clean purge_all Restore Defaults Apply Tracing the STAPI SDK application When the STAPI SDK application has been built it can be debugged and traced in the STWorkbench debugger STAPI SDK can launch the STWorkbench debugger using the following command gmake debug STWORKBENCH 1 Alternatively if STAP SDK has been built in STWorkbench then the debugger can be launched when a debug configuration has been created Doc ID 8254555 Rev A 13 19 14 19 User API trace and events in STAPI SDK ST40 toolset user trace support Figure 14 shows a typical Run or Debug configuration for the STAPI SDK application Run Configurations Figure 14 Typical Run Debug configuration for the STAPI SDK Application Create manage and run configurations Hx EF Name SDK_Build HDK7111 type filter text E Main 69 Arguments Environment s Debugger
19. very Options Environment Tool Settings Build Steps P Build Artifact la Binary Parsers Error Parsers Settings i id ji Tool Chain Editor 5740 C Compiler Linker flags Wl myapp wrap ld E C C General Preprocessor Project References Refactoring History Run Debug Settings Other options Xlinker option symbols Directories amp Optimization Debugging Warnings 3 Miscellaneous Compiler Linker Shared Settings ST40 C Linker amp General Other objects Libraries Miscellaneous Relocatable Library Compiler Linker Shared Settings 5T40 Assembler General he Doc ID 8254555 Rev A 7 19 Example of performing a user API trace ST40 toolset user trace support When the build options have been set in STWorkbench the example can be built When building the application in STWorkbench the operation generates the command lines shown in Figure 7 Figure 7 Console window output when building the example Build of configuration Debug for project led out make pre build main build os2lusertrace d myapp in g myapp cmd 1 myapp wrap ld s myapp wrap c myapp def Building file led c Invoking ST40 C Compiler sh4gcc D__mb680sti7105__ 00 g Wall c fmessage length 0 mboard mb680sti7105 mruntime os21 ml trace trace api MMD MP MF led d MT led d o led o led c Finished building led c
Download Pdf Manuals
Related Search