Getting started with IAR Embedded Workbench and NXP i.MX RT

This is the first step in understanding how to develop complete programs with IAR Embedded Workbench for Arm. In this guide, you will explore the compiler, linker and debugger setup through the following steps:

• Generate a project
• Set compiler and linker options
• Prepare debugger settings 
• Download and debug

The instructions are written for V.8.20 of IAR Embedded Workbench for Arm but older versions of the toolchain will resemble the screenshots in this document. If you don’t have a license of the toolchain already, you can register for an evaluation version. When everything is installed and ready, it is time to start the fun!

Generate a project

1. Create a new folder and name it test; start IAR Embedded Workbench for Arm. Once the toolchain is running, you will notice that the Information Center is displayed.
   
   From the Information Center, you can view the example workspaces for your board. For this example, however, we will be building our own application from scratch.
   
   
2. Choose File>New>Workspace. You should now have a empty slate that looks like this:
   
3. Now, you need to add a project to our workspace. The project will contain the source code for our application. Choose Project>Create New Project. Select C and main in the dialog box and click OK.
   
   You will be asked where you would like to store our project. Choose your newly-made folder and name the project Hello and click Save. Now, you have a project with a main.c file.
   
4. Next step it to add some code to your project, for example a printf statement with its suitable library.
   
   Notice that there is a red asterisk next to the main file – this indicates that the code will be compiled at the next build either because the source is new or because it has changed since the last build. After compilation, the asterisks will disappear until we make a change to the code. Your screen should look now like this:
   
5. In the Workspace window, right-click on the project and choose Options. In the General Options category, set the Target to be NXP MIMXRT1052xxx6A.
   
   Build your project by either choosing Project>Make, by pressing F7, by clicking the Make button on the toolbar, or by right-clicking on the project in the Workspace window. When you do this, IAR Embedded Workbench will save all source code and will pop up a window to ask you what name you want to give to the overall workspace. In this window, name the overall workspace Test and save it in your workspace directory.
   
   Hopefully you will get no error messages or warnings.

Now it’s time to see what your application will do!

1. In the Project>Options>Debugger>Setup, set the driver to CMSIS DAP and click OK. Plug in a USB Micro cable into the port marked “Debug USB” on the board. Now click the Download and Debug button.
   
   Note that the simulator will start running and the program will halt at the entry point of the function main.
   
2. At this point, you can open the View menu and select Terminal I/O. You can also rearrange the open windows as you like.
   
   
3. Click the C-SPY Go button. Observe what happens in the Terminal I/O window.
   
   
4. Stop the debugging with the Halt button.

Set compiler and linker options

To set the correct options for the compiler and linker, right-click the project in the Workspace window and choose Options. Now, go through the following:

General Options category 

1. Click the Output tab and make sure that Executable is selected since we will be ultimately downloading this to the evaluation board instead of creating a library to be used in another application.
   
   
2. In the Library Configuration tab, you can choose which configuration to use. In this project, make sure that your runtime library is set to Normal. Other library options allow you to manually select the printf/scanf formatters, but we will leave these alone for this project.

C/C++ Compiler category

1. In the Language tabs, you can choose a number of variants, for example which C dialect to use and whether or not to require function prototypes in your code. Set C99 and C++ inline semantics for this project.
   
   
2. In the Optimizations tab, notice that the default behavior for the Debug release configuration is to have Low optimization. You can change this to whatever you like, but notice that when you choose Medium or High optimization, you can choose which transformations are applied to the code.
   
   Details about each transformation can be found in the user guide IAR C/C++ Development Guide for Arm.
   
   
3. In the Output tab, make sure that Generate debug information is selected. If you are attempting to debug code and the C-SPY debugger complains that there is no definition for main( ), it is probably because this box has not been selected. This needs to be selected so that the debugger can reference the source code to the disassembly.
   
   
4. In the Preprocessor tab, you can add additional directories for the compiler to search for include files. Be sure to use environment variables such as $PROJ_DIR$ (which resolves to where the project’s .ewp project file is located) to make your project portable, e.g.: $PROJ_DIR$\include\.
   
   You can also define global #defines in this tab, such as DEBUG which would be equivalent to putting #define DEBUG in your code.

Linker category

1. In the Config tab, you will notice that $TOOLKIT_DIR$\config\flashloader\NXP\FlashIMXRT1050_EVK_FlexSPI.board is selected as our linker configuration file. This file is selected as default when you choose the NXP MIMXRT1052xxx6A device as the target.
   
   If you want to change linker configuration file, just select Override default and then click the browse button to open a file browser dialog box. We do not need to do that in this example.
   
   
2. In the Output tab, make sure that Include debug information in output is selected so that the C-SPY debugger will be able to link our source code to the disassembly.
   
   
3. In the List tab, check the box for Generate linker map file. This file will show us where our code modules are going in the final application, as well as their sizes.

Click OK to save all the changes we have made, build our project and see if you get any messages. The project should build successfully without errors or warnings.

Prepare debugger settings 

1. Build the test project again and in the Workspace window, click the plus sign next to the Output folder to see its contents. You will see that it includes the application and the map file. The map file contains the addresses and locations of all code and data that is used in the application. It also tells you how big the application’s footprint is.
   
2. Double-click the map file in the Workspace window and you will see what the sizes of our modules are and where they are placed. Near the end of this file, we see that the main( ) function is located at address 0x00001631 and is of size 0x1c bytes. (The location and size may vary depending on the settings you chose and which version of IAR Embedded Workbench for Arm you use.)
   
3. If you want to see the sizes of the individual files as well as the size of the overall application, you can set the Build Messages window to provide this information. Right-click in the Build window and choose All to see all the build messages.
   
   
4. Now, let’s move the main( ) function to address location 0x00002000. We can do this by adding a pragma directive just before the main( ) function: On the line before int main( ), add this line: 
     #pragma location="MyMainFunction"
   
   
5. Copy the MIMXRT1052xxx6A.icf, from folder indicated in Project>Options>Linker>Config, to your project directory. 
   
   
6. Remember to specify $PROJ_DIR$\MIMXRT1052xxx6A.icf on the Options>Linker>Config page. Open the file in a text editor and  find the line:

place at address mem:__ICFEDIT_intvec_start__ { readonly section .intvec }; 

7. Once you have located this line, place the following line just after it:

place at address mem:0x00002000      {section MyMainFunction};

8. Now, return to the project and do a Rebuild All.  You will notice that in the map file, the location for the main( ) function has changed.

In an Arm Cortex-M architecture, the code has to be odd-byte aligned.

Download and debug

Some notices to start with:

• Notice that on Project>Options>Debugger>Setup, there are many different hardware debugger options. The one currently in use is the CMSIS DAP debugger, but for the production hardware we recommend you to choose our debug probe I-jet.
  

• Notice on this page, the Device descriptor File (*.ddf) was already selected when you chose the NXP MIMXRT1052xxx6A in General Options. The DDF provides the addresses and names of the Special Function Registers (SFRs) on the MCU.

• Notice the Run to main option. By default, this option is selected. When selected, the behavior for debugging will be to have the MCU run through all the startup code and then halt on the first statement of main. If not selected, the debugging session will break at the first instruction of the startup code, just as if the board has gone through the reset vector.

You are now ready to download and debug your application!

1. Click OK to close the Project Options window and then click the Download and Debug button. Click Go.

Let’s work with some breakpoints.

1. Halt the MCU. In main.c, change the code to look like the following:

  printf("Hello world!\n");   
  static int loopCounter = 0;   

  while   (1U)  
  {    
      loopCounter++; 
  }   

   return 0;

2. Set a breakpoint on loopCounter by right-clicking the line and choose Toggle Breakpoint (Code). Now, click Run and you quickly hit the breakpoint.

3. Click View->Breakpoints to see the Breakpoints window. Right-click the breakpoint you just created and choose Edit. In the Condition field, type:

loopCounter >= 10

4. Hit run – the breakpoint will only trip when the condition becomes true.

5. You can also use the Skip Count in the Edit window to make the breakpoint only trip after the line of code has been executed the number of times indicated in the Skip Count field.

7. In the Breakpoints window, delete the breakpoint you just set.

8. Right-click the same loopCounter line that you did in step 1 and choose Toggle Breakpoint (Log). In the Breakpoints window, right-click the log breakpoint you just created and click Edit. Check the box for “C-SPY macro message style” and put the following in the dialog box:

Note that it is a comma between the quotation mark and loopCounter, not a period.

9. Click OK.

10. At the bottom of the IDE, click the tab to open the Debug Log. Scroll to the bottom of the log window and then click Run; you will now see the value of loopCounter printed in the Debug Log window each time is passes through that section of code:

This gives you the power of doing printf( ) statements in your code without actually instrumenting your code with printf( ) statements so that when you go to Release mode, you don’t have to remove a bunch of statements from your project!