Configuring and implementing a visualstate target application for debugging with IAR visualstate RealLink

Transcription

1 Configuring and implementing a visualstate target application for debugging with IAR visualstate RealLink The information in this document is based on versions 4.2 and 4.3 of the IAR visualstate software. It may also apply to subsequent versions of IAR visualstate. SUMMARY Using IAR visualstate RealLink to debug your application at run-time enables you to monitor and control your application from the visualstate Validator. This application note describes how you set up, implement and build your visualstate application to support RealLink, and how you establish a connection between the Validator and your target. KEYWORDS Debugging visualstate models, IAR visualstate RealLink, run-time, target application, IAR visualstate RealLink API, IAR visualstate Validator. The problem to be solved A standard visualstate application does not support RealLink. How do I modify a visualstate Project so that it can be used with the Validator RealLink? Solution To get RealLink configured and ready for your project, the following steps must be completed: Step 1: Enabling RealLink support, page 2. Step 2: Adding RealLink files to your project, page 6. Step 3: Using the RealLink API, page 6. Step 4: Implementing target-specific functions, page 7. Step 5: Completing the target source code, page 8. Step 6: Setting up the RealLink connection, page 8. 1

2 Step 1: Enabling RealLink support The following figures were taken from the AVSystem example included in the visualstate software. The procedure described here for enabling RealLink applies to any visualstate Project. The arrows ( ) in the screen captures point to areas of interest. visualstate Coder settings that are not marked with an arrow do not have any influence on RealLink and can be configured to suit your application. 1 First of all start IAR visualstate Navigator and open the visualstate Project for which to enable RealLink support. In the Project browser, right-click on a visualstate System, and select Properties from the pop-up menu. See Figure 1. Figure 1: Selecting System properties in the Navigator 2 In the Properties dialog box displayed, click on the Build tab. The left pane of the dialog box shows a number of Coder option groups. Select the following RealLink-related Coder options in order to enable RealLink support for your visualstate Project: 2

3 General settings: Select Generate digital signature. Under RealLink mode, select Table based. See Figure 2. Figure 2: Navigator Build tab, General settings Name convention: Select the Use action pointer table option. See Figure 3. Figure 3: Navigator Build tab, Name convention 3

4 Code comments: Under Function Expression Handling, select Function Pointer Tables. See Figure 4. Figure 4: Navigator Build tab, Code comments Advanced settings: Make sure that the Optimize states and machines option is not selected. Select the Enable SEM_InitAll or <system_name>smp_initall option. See Figure 5. Figure 5: Navigator Build tab, Advanced settings 4

5 Basic API functions. Select the SEM_Inquiry and SEM_GetInput option if there are sufficient resources (for information on resource usage, see IAR visualstate API Guide). See Figure 6. Figure 6: Navigator Build tab, Basic API functions 3 Click the OK button to accept the visualstate Coder settings. 4 Save the visualstate Project, and select Tools > Build All to generate the source code for the visualstate System. See Figure 7. Figure 7: Navigator Build All command Code generation will start, and a code generation results report will be written to the Navigator Output window (opened via View > Output). If some of the RealLink options were not selected, the Coder will inform you of the missing option(s). In such cases, select the missing option(s) and perform another Build All. 5

6 Step 2: Adding RealLink files to your project In order to successfully compile and link your project with RealLink support, you must add the following two C modules to your compiler project (or make file): RealLink.c VSrlps.c The C module RealLink.c includes the C header file RealLink.h. The RealLink.h file must also be included in the file containing the visualstate deduction sequence (a sequence of the visualstate API functions SEM_Deduct, SEM_GetOutput, SEM _NextState). See Example of main function, page 6. RealLink.c and RealLink.h are the RealLink API files, which are included with the visualstate standard installation. The files are located in the \IAR Systems\IAR visualstate X.x\Lib\SEMLibRealLink directory. The VSrlps.c file is a RealLink support file that is generated by default. The file is placed in the output directory specified in General settings on the Build tab, together with the other Coder-generated files (see Figure 2, page 3). Note:Do not manually edit the VSrlps.c file because it will be overwritten during the next code generation. Refer to your compiler manual on how to add additional source files to an existing project. Step 3: Using the RealLink API To use the RealLink API, you must make the following changes to your code: 1 Include RealLink.h in the file containing the visualstate deduction sequence. 2 Call the Basic API function SEM_InitAll(). (This replaces calls to the Basic API initialization functions such as SEM_Init(), SEM_InitSignalQueue(), etc.). 3 Call the RealLink API function VS_RealLinkInit(). 4 Insert the RealLink API macro VS_WAIT() in the main loop. The main loop is identified by an infinite loop, typically a while(1) or for(;;) loop. Note:The VS_WAIT() macro must not be inserted inside the visualstate deduction sequence. See Example of main function, page 6. When the visualstate application enters the VS_WAIT() macro, data is exchanged between the Validator and the target. When data exchange is completed, the visualstate application program resumes execution, according to your commands from the Validator. Example of main function Below is an example of a simple main function including a main loop with a visualstate deduction sequence that has been modified to support RealLink. Note that the VS_WAIT() macro is outside the visualstate deduction sequence. 6

7 The code that you must insert is shown in bold. Initialization Main loop visualstate deduction sequence Step 4: Implementing target-specific functions Because both the visualstate and RealLink APIs are target-independent, they contain no information on how to use the communication device of the target. 1 In order to access the communication device you must implement the following target-specific RealLink functions which are used by the visualstate API: A transmit function that transmits one character to the communication device. The default name of the function is RealLinkTransmit(). The function will be called by the RealLink API. An interrupt-driven receive function that receives characters from the communication device. The received characters should be passed to the RealLink protocol by calling the function VS_RealLinkReceive(). A reset function that is capable of resetting the target. The default name of this function is RealLinkReset(). The function will be called by the RealLink API. TIP: IAR MakeApp can be used to automatically generate interrupt functions. 2 Include RealLink.h in the file where the RealLinkTransmit() and RealLinkReset() functions are implemented. Examples of implementation of the functions are shown below. The functions were implemented using the following Microprocessor: Hitachi SH7440. Compiler: From IAR Systems. 7

8 Example: Transmit function /* * Function : RealLinkTransmit * Purpose : Transmit one character on the communication device * Parameters : ch = character to transmit * */ VS_VOID RealLinkTransmit(VS_UINT8 ch) { while(!(sci_ssr1 & 0x80) ) { /* wait for transmit register empty ---*/ } ; SCI_TDR1 = ch; SCI_SSR1 &= ~0x01; /* MPBT is cleared */ SCI_SSR1 &= ~0x80; /* TDRE is cleared */ } Note:The function does not transmit new data until the transmit register is empty. Example: Receive function /* * Function : RealLinkReceive * Purpose : Receives characters from the communication device. * Parameters : - * * Notes : The communication must be interrupt-driven. Each * character received must be sent to * VS_RealLinkReceive() */ VS_VOID RealLinkReceive(VS_VOID) #pragma vector=sci_rxi1 interrupt VS_VOID RealLinkReceive(VS_VOID) { unsigned char ch; ch = SCI_RDR1; SCI_SSR1 &= ~0x40; /* RDRF is cleared */ } VS_RealLinkReceive(ch); /* The RealLink API function is called */ Example: Reset function /* * Function : RealLinkReset * Purpose : Reset the microcontroller * Parameters : - * */ VS_VOID RealLinkReset(VS_VOID) { /* push 0 on the stack and perform a return */ asm("push 0"); asm("rtn"); } Step 5: Completing the target source code When the preceding steps have been completed, the target source code is ready and can be embedded in the target. 1 Compile and link the complete project. 2 Embed the source code in the target. Step 6: Setting up the RealLink connection By now the target application should be ready and embedded. The next step is to configure the RealLink connection. 8

9 In this example the target is connected to the PC where visualstate is running by means of an RS232 connection. RealLink must have exclusive access to the serial port; it cannot be shared with other programs. You will get an error message if trying to open a serial port that is already in use by another program. Setting up communication module The Validator must be configured before the RealLink connection can be established. 1 Launch the Validator. 2 From the menu select RealLink > Properties to configure RealLink. See Figure 8. Figure 8: Configuring RealLink The following dialog box will be displayed: Figure 9: RealLink properties dialog box 3 When the dialog box opens, it will scan the default directory for RealLink communication modules (progress is shown in the status line). The default directory is the \IAR visualstate X.x\Bin directory. To scan other directories, click the... button (Browse button) to specify the directory to scan for available communication modules. 4 The Active Module drop-down list shows the currently active communication module. Click the drop-down arrow to select another RealLink communication module located in the current directory. Select the module to apply. 5 When a communication module has been selected, it must be configured to the communication settings of the target. Click the Configure button. The following dialog box will be displayed: 9

10 Figure 10: RS232 Setup dialog box Because different communications modules have different properties, the module setup dialog boxes will differ. Figure 10 shows the setup dialog box for the RS232 module supplied with visualstate. 6 Fill in the Setup dialog box with the appropriate settings, which must match the target settings. Click OK. Subsequently click OK in the RealLink Properties dialog box (see Figure 9). Establishing the first RealLink connection When the communication module has been configured, the RealLink connection can be established. 1 On the Validator menu, select RealLink > Connect as shown in Figure 11. Figure 11: Connecting to RealLink If the connection is successfully established, the Validator Output window (RealLink tab) will display the message shown in Figure 12. Figure 12: Validator Output window 10

11 When a connection has been successfully established between the Validator and the target, it is possible to debug the application from within the Validator. This is described in IAR Application Note Debugging with IAR visualstate RealLink. Conclusions By using the method described above, a visualstate target application can be modified so as to support RealLink. References IAR Application Note Debugging with IAR visualstate RealLink. IAR visualstate User Guide. IAR visualstate API Guide. Contact information SWEDEN: IAR Systems AB P.O. Box 23051, S Uppsala Tel: / Fax: info@iar.se USA: IAR Systems US HQ - West Coast One Maritime Plaza, San Francisco, CA Tel: / Fax: info@iar.com USA: IAR Systems - East Coast 2 Mount Royal, Marlborough, MA Tel: / Fax: info@iar.com UK: IAR Systems Ltd 9 Spice Court, Ivory Square, London SW11 3UE Tel: / Fax: info@iarsys.co.uk GERMANY: IAR Systems AG Posthalterring 5, D Parsdorf Tel: / Fax: info@iar.de DENMARK: IAR Systems A/S Lykkesholms Allé 100, DK-8260 Viby J Tel: / Fax: info@iar.dk Copyright 2001 IAR Systems. All rights reserved. The information in this document is subject to change without notice and does not represent a commitment on any part of IAR Systems. While the information contained herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors or omissions. visualstate is a registered trademark of IAR Systems. IAR visualstate RealLink, IAR Embedded Workbench and IAR MakeApp are trademarks of IAR Systems. Microsoft is a registered trademark, and Windows is a trademark of Microsoft Corporation. All other product names are trademarks or registered trademarks of their respective owners. May