Application note Porting a Green Hills SW to SPC5Studio Introduction SPC5Studio provides a comprehensive framework to design, build and deploy embedded applications for SPC56 Power Architecture 32-bit microcontrollers. It combines a project editor a sophisticated code generator, a GNU C compiler and other utilities. The aim of this tutorial is to guide the programmers in adapting SPC56x microcontrollers SW applications written with Green Hills compiler to SPC5Studio environment and its HighTec compiler. June 2014 DocID026145 Rev 2 1/22 www.st.com
Contents AN4464 Contents 1 Overview.................................................. 5 2 Steps for porting a Green Hills SW to SPC5Studio................ 6 3 SPC5Studio setting up and configuration....................... 8 3.1 Creating a new project in SPC5Studio............................ 8 3.2 Adding STMicroelectronics SPC560x platform component........... 10 3.3 STMicroelectronics SPC56x platform component configuration....... 12 3.4 Adding SPC5-HAL SPC56x OS-Less OSAL component............. 12 3.5 Import application files and update main.c file in SPC5Studio......... 13 3.6 Configuring SPC5-HAL SPC56x OS-Less OSAL component......... 14 3.7 User s ISR and vector table................................... 16 3.8 Different compilers issue..................................... 16 3.8.1 Language variations or dialect issues.......................... 16 3.8.2 Library issues............................................. 17 4 Generating the code, building and debugging................... 18 4.1 Generating and building the application SW...................... 18 4.2 Debugging the SPC5Studio application.......................... 19 5 Revision history........................................... 21 2/22 DocID026145 Rev 2
List of tables List of tables Table 1. Document revision history................................................. 21 DocID026145 Rev 2 3/22 3
List of figures AN4464 List of figures Figure 1. Steps for porting a GHS application in SPC5Studio............................... 7 Figure 2. SPC5Studio application wizard welcome....................................... 8 Figure 3. Creating a new project 1/3.................................................. 9 Figure 4. Creating a new project 2/3.................................................. 9 Figure 5. Creating a new project 3/3................................................. 10 Figure 6. Application configuration editor.............................................. 11 Figure 7. Adding STMicroelectronics SPC560x platform component to SPC5Studio............ 11 Figure 8. Configuring SPC56x platform component..................................... 12 Figure 9. Adding SPC5-HAL SPC56x OS-Less OSAL component to SPC5Studio.............. 13 Figure 10. Importing application files in the SPC5Studio project............................. 14 Figure 11. main.c file in SPC5Studio.................................................. 14 Figure 12. Insert an interrupt vector to be enabled at startup............................... 15 Figure 13. Configuring SIU_External_IRQ_0 interrupt vector............................... 15 Figure 14. Save, generate and build the application SW................................... 18 Figure 15. The build folder in Project explorer.......................................... 18 Figure 16. Debug.wsx in SPC5Studio Explorer.......................................... 19 Figure 17. Loading binary file........................................................ 19 Figure 18. Flashing microcontroller................................................... 20 Figure 19. Start program execution................................................... 20 4/22 DocID026145 Rev 2
Overview 1 Overview This application note guides the programmers in adapting GHS SW application written for SPC56x microcontrollers to SPC5Studio tool with its HighTec compiler. SPC5Studio configuration and setting up for porting is shown in Chapter 3: SPC5Studio setting up and configuration. Code generation, building and debugging of the proposed example application is shown in Chapter 4: Generating the code, building and debugging. Some of the differences between the GHS and HITECH compilers in terms of conformance to the C language standard and library support are described in general terms. These information help the user to determine the amount of effort required to port the source code to SPC5Studio. DocID026145 Rev 2 5/22 21
Steps for porting a Green Hills SW to SPC5Studio AN4464 2 Steps for porting a Green Hills SW to SPC5Studio In order to port a SW application written with Green Hills (GHS) in SPC5Sudio, two approaches can be followed, depending on if SPC5-HAL SPC56Xxx OS-Less OSAL Component is used in SPC5Studio or not. The steps to follow for each approach are described below: Approach 1 using SPC5-HAL SPC56Xxx OS-Less OSAL Component 1. Create a new project in SPC5Studio 2. Add into SPC5Studio the STMicroelectronics SPC56Xxx Platform Component correspondent to the microcontroller used in the porting 3. Add into SPC5Studio the SPC5-HAL SPC56Xxx OS-Less OSAL Component for managing the vector table and interrupts 4. Copy the application files with extension *.c, *.h, *.asm and the main.c content from the original GHS project into SPC5Studio project. 5. Configure SPC5-HAL SPC56Xxx OS-Less OSAL Component adding interrupts according to the interrupt routines present in the original GHS application. 6. Manage different compilers issue, if any 7. Generate code in SPC5Studio 8. Compile SPC5Studio project 9. Debug the application Approach 2 without using SPC5-HAL SPC56Xxx OS-Less OSAL Component 1. Create a new project in SPC5Studio 2. Add into SPC5Studio the STMicroelectronics SPC56Xxx Platform Component correspondent to the microcontroller used in the porting 3. Copy the application files with extension *.c, *.h, *.asm, the main.c content from the original GHS project into SPC5Studio project. 4. Create your own vector table and interrupt managing files in SPC5Studio and update user.mak file 5. Manage different compilers issues, if any 6. Generate code in SPC5Studio 7. Compile SPC5Studio project 8. Debug the application 6/22 DocID026145 Rev 2
Steps for porting a Green Hills SW to SPC5Studio Figure 1. Steps for porting a GHS application in SPC5Studio Create a new SPC5Studio project Add STMicroelectronics SPC56Xxx Platform Component Approach 1 Approach 2 Add SPC5-HAL SPC56Xxx OS-Less OSAL Component Approach 1 Copy application files *.c, *.h, *.asm, main in SPC5Studio project Approach 1 Approach 2 Configure SPC5-HAL SPC56Xxx OS-Less OSAL Approach 1 Create your own vector table and interrupts Approach 2 Manage possible different compilers issue Generate code and compile in SPCStudio Debug DocID026145 Rev 2 7/22 21
SPC5Studio setting up and configuration AN4464 3 SPC5Studio setting up and configuration 3.1 Creating a new project in SPC5Studio For porting purpose the first step is to create a new project in SPC5Studio. Run SPC5Studio.exe file placed in SPC5Studio installation directory C:\SPC5Studio\eclipse. SPC5Studio application wizard welcome is open (see Figure 2). Figure 2. SPC5Studio application wizard welcome 8/22 DocID026145 Rev 2
SPC5Studio setting up and configuration 1. Click on File->New->C Project Figure 3. Creating a new project 1/3 2. Select SPC5 C Application in the Makefile project folder Figure 4. Creating a new project 2/3 DocID026145 Rev 2 9/22 21
SPC5Studio setting up and configuration AN4464 3. Set the project name, the version and a short description, these values can be changed at any time. Check the Standalone if you want the project to be compiled also outside Eclipse. Figure 5. Creating a new project 3/3 At the end of these three steps you have an empty project, the next step is to add the platform component. 3.2 Adding STMicroelectronics SPC560x platform component The application wizard permits to add components to the project easily and without having to worry about integration. In particular: Project files (Makefiles) are automatically updated when a component is added. The user does not have to copy any system file in the project. Components dependencies are automatically checked by the wizard. Components are configured easily using a wizard. The component configuration can be modified at any time. The project source tree is automatically updated each time components are added. Components are automatically initialized by code generated automatically To add the components to the project click on the configuration.xml file in project explorer (see Figure 6), the Application Configuration Editor opens. 10/22 DocID026145 Rev 2
SPC5Studio setting up and configuration Figure 6. Application configuration editor The configuration.xml file has 4 tabs (see Figure 6), the Structure tab permits to assemble the application, to add components and to configure them. In the Structure tab click on the green cross to choose the platform component used for the porting (see Figure 7). Startup files and linker scripts for SPC560x microcontroller are created when the code is generated. Figure 7. Adding STMicroelectronics SPC560x platform component to SPC5Studio DocID026145 Rev 2 11/22 21
SPC5Studio setting up and configuration AN4464 3.3 STMicroelectronics SPC56x platform component configuration To configure SPC56x platform component proceed as follow (see Figure 8): Specify the microcontroller you are using for the porting in the Platform Settings section: Set the process stack size and the IRQ Stack size in section Runtime Settings: the default values are Process Stack Size = 2048 and IRQ Stack Size = 0, if necessary these values can be changed In Build Settings section you can leave the default values of configuration but for debugging purpose set the value Optimization level to -O0 Linker setting: leave default values Figure 8. Configuring SPC56x platform component 3.4 Adding SPC5-HAL SPC56x OS-Less OSAL component If the approach 1 has been chosen, the next step is to add the SPC5-HAL SPC56x OS-Less OSAL component into SPC5Studio project. This component implements: Vectors table ISR servicing code ISR declaration macros Interrupt manipulation function and macros Selecting the platform component in the components explorer and clicking on the green cross on the configuration editor, select the SPC5-HAL/SPC560x/SPC5-HAL SPC56x OS-Less OSAL and click OK to add the component to the project (see Figure 9). 12/22 DocID026145 Rev 2
SPC5Studio setting up and configuration The configuration of this component is shown in the paragraph Section 3.6, let s first add the application files available in GHS to SPC5Studio project. Figure 9. Adding SPC5-HAL SPC56x OS-Less OSAL component to SPC5Studio 3.5 Import application files and update main.c file in SPC5Studio In the original GHS sw written for SPC56Xxx microcontroller there are the files related to the application that have to be imported to SPC5Studio. The GHS system files have to be ignored and not imported. The main.c file from the original application has not to be imported but its content has to be copied in the main.c file already available in SPC5STudio. The linker file, the make file are provided by SPC5Studio platform component, the vector table and interrupt management from osal component. Supposing that the application files with extension *.c, *.h and *.s in the original GHS application are named file_1.c, file_2.c, file_3.asm, file_1.h and file_2.h, copy these files in the folder source/src and source/include of SPC5Studio project as shown in Figure 10. DocID026145 Rev 2 13/22 21
SPC5Studio setting up and configuration AN4464 Figure 10. Importing application files in the SPC5Studio project Modify SPC5Studio main.c file Copy the main.c content from the original GHS application into the main.c file of the SPC5Studio in the application entry point, see Figure 11 Figure 11. main.c file in SPC5Studio 3.6 Configuring SPC5-HAL SPC56x OS-Less OSAL component This step has to be implemented if approach 1 has been chosen. 14/22 DocID026145 Rev 2
SPC5Studio setting up and configuration In Section 3.4 is shown how to add SPC5-HAL SPC56x OS-Less OSAL component in SCP5Studio. Now it is needed to configure it according to the interrupts present in the original GHS application. Let s suppose that the original application in a SPC560Bxx microcontroller has got a SIU_External_IRQ_0 corresponding to vector 41 and that its interrupt priority level is equal to 1 (INTC.PSR[41].R = 0x1). Let s suppose the interrupt routine is the one shown below, named SIU_External_IRQ_0 and available in one of the file.c imported: void SIU_External_IRQ_0 (void) { SIU.ISR.B.EIF0 = 1; LED_switch(led2,0); } To configure this interrupt vector select in the components explorer SPC5-HAL SPC56x OS-Less OSAL component and click on the green cross to add an interrupt vector, see Figure 12. Figure 12. Insert an interrupt vector to be enabled at startup Double clicking on the interrupt vector it is possible to configure it as shown in the Figure 13. Figure 13. Configuring SIU_External_IRQ_0 interrupt vector DocID026145 Rev 2 15/22 21
SPC5Studio setting up and configuration AN4464 For each interrupt imported in the SW it has to be added and configured an input vector as shown in Figure 12 and Figure 13. After the interrupts configuration it is needed to globally enables them (interrupts) adding in the main.c file the command: osalisrenable(). 3.7 User s ISR and vector table The SPC5-HAL SPC56Xxx OS-Less OSAL component is not added in the approach 2. In this case the user has to implement: the Vector table the ISR servicing code the ISR declaration macros the interrupt functions managing porting the original GHS application interrupt routines to SPC5Studio 3.8 Different compilers issue The inevitable differences in language syntax and implementations between two different compilers could be the principal obstacle for a quick porting. Many of the problems encountered in porting a GHS C source code for a SPC56Xxx microcontroller to HighTec C source code for the same microcontroller can be split into 2 categories. These are: language variations library issues 3.8.1 Language variations or dialect issues The source compiler (GHS) and the target compiler (HighTec) could interpret a C program differently, can be based on a different standard or the two compilers might be not updated in supporting features of the latest standard. Whatever the reason this creates problems in the source code where the compilers diverge. Other problems come from the use in the SW of language extensions or features provided by the source compiler that are not present on the target compiler. These extensions provide features, as for example flexible initialization syntax for arrays and structures and support for complex numbers. Surely useful, these extensions can create code porting problems. Some of these extensions can be easy to port while others could have not an equivalent on the target compiler. Because each compiler could implement its own dialect of the language, during the porting there could be the need to modify the code so that it is acceptable to the other compiler. Pragma directives control compiler behavior by allowing individual compiler implementations to add special features to C without changing the C language. Programs that use #pragma are relatively portable, although they make use of features unavailable in all ANSI C implementations. The ANSI standard states Any pragma that is not recognized by the implementation is ignored. This requirement may help when porting code between compilers, because one compiler will silently recognize and process a certain pragma, while a different compiler which does not need that pragma or recognize it ignores it. The majority of Green Hills proprietary #pragma begin with the keyword ghs to differentiate them from other implementations. 16/22 DocID026145 Rev 2
SPC5Studio setting up and configuration 3.8.2 Library issues Many compilers allow the programmer to use the services provided by the host machine s system libraries. In this case most of the porting problems in this category are due to missing library functions. Differences in the header files that define the interfaces to the library can play an important role. DocID026145 Rev 2 17/22 21
Generating the code, building and debugging AN4464 4 Generating the code, building and debugging 4.1 Generating and building the application SW Up to now all the steps needed for the porting have been shown. The next step is to generate code and build it even if this could be done at any time during the development of a SPC5Studio project. To generate the code click on the icon Generate code (3), having first saved the project clicking on save icon (1), see Figure 14. Figure 14. Save, generate and build the application SW Clicking on Generate code icon (3) SPC5Studio generates the following files: source codes (*.c and *.s) Header files (*.h) Makefiles & scatter file (*.ld) At this point it is possible to build the project clicking on build all icon (2). A build folder is created containing all the files generated by the build command: elf file (bin, hex and dmp) and map file, see Figure 15. Figure 15. The build folder in Project explorer 18/22 DocID026145 Rev 2
Generating the code, building and debugging 4.2 Debugging the SPC5Studio application The build command mentioned in the Section 4.1 generates the UDE folder in SPC5Studio project explorer. Double clicking debug.wsx file (see Figure 16) UDE Visual Platform is opened allowing to flash the microcontroller with the ported application. Figure 16. Debug.wsx in SPC5Studio Explorer Click Load on the Loading binary target file window, see Figure 17. Figure 17. Loading binary file Click on Program All button to flash the microcontroller, see Figure 18. DocID026145 Rev 2 19/22 21
Generating the code, building and debugging AN4464 Figure 18. Flashing microcontroller Clicking on Start Program Execution (see Figure 19) the processor runs and program stops at the beginning of the main routine break point, the ported application SW is ready to be debugged. Figure 19. Start program execution 20/22 DocID026145 Rev 2
Revision history 5 Revision history Table 1. Document revision history Date Revision Changes 09-Apr-2014 1 Initial release. 05-Jun-2014 2 Updated Chapter 2- Updated Section 3.5 and deleted Figure 11. DocID026145 Rev 2 21/22 21
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 of 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. ST PRODUCTS ARE NOT DESIGNED OR AUTHORIZED FOR USE IN: (A) SAFETY CRITICAL APPLICATIONS SUCH AS LIFE SUPPORTING, ACTIVE IMPLANTED DEVICES OR SYSTEMS WITH PRODUCT FUNCTIONAL SAFETY REQUIREMENTS; (B) AERONAUTIC APPLICATIONS; (C) AUTOMOTIVE APPLICATIONS OR ENVIRONMENTS, AND/OR (D) AEROSPACE APPLICATIONS OR ENVIRONMENTS. WHERE ST PRODUCTS ARE NOT DESIGNED FOR SUCH USE, THE PURCHASER SHALL USE PRODUCTS AT PURCHASER S SOLE RISK, EVEN IF ST HAS BEEN INFORMED IN WRITING OF SUCH USAGE, UNLESS A PRODUCT IS EXPRESSLY DESIGNATED BY ST AS BEING INTENDED FOR AUTOMOTIVE, AUTOMOTIVE SAFETY OR MEDICAL INDUSTRY DOMAINS ACCORDING TO ST PRODUCT DESIGN SPECIFICATIONS. PRODUCTS FORMALLY ESCC, QML OR JAN QUALIFIED ARE DEEMED SUITABLE FOR USE IN AEROSPACE BY THE CORRESPONDING GOVERNMENTAL AGENCY. 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 trademark of STMicroelectronics. All other names are the property of their respective owners. 2014 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 22/22 DocID026145 Rev 2