Programming with CodeWarrior IDE 02/11/2006

Programming with CodeWarrior IDE

This document gives you an introduction to the programming environment you will be using in the course for the development of embedded software systems for the MCF5213 microcontroller. You will also be introduced to the main I/O devices that are available. Step-by-step instructions will be provided to guide you through the development of simple applications. It is important that you understand the motives and the activities of each of these steps. In future laboratory exercises, it will be assumed that you are capable of reproducing these steps, as well as modify them to suite your needs. For this reason, you should take the opportunity to enquire about any uncertainties you meet. Try to answer the questions posed as they will give you more insight into the environment. The tutorial is divided into 4 sections. Part A introduces the laboratory hardware. Part B introduces the CodeWarrior programming environment, as well as experiment with some C programming. Part C introduces the basic I/O modules built-in the MCF5213. This will give you extra opportunities to practice your programming skills. Part D will introduce additional I/O devices and their drivers.

Programming with CodeWarrior IDE 02/11/2006

1 Part A Hardware Setup

In this course, you will be working using the following hardware setup: MCF5213EVB Interface Card

Motor Card

Power UART0 Microcontroller Sw1 & Sw2 BDM Interface LEDs

LCD Switches Microcontroller Potentiometer Keyboard LEDs

Programming with CodeWarrior IDE 02/11/2006

2 Part B CodeWarrior IDE

First, it is important to get familiar with certain terms and concepts that will be used through this tutorial: Integrated Development Environment (IDE) (also known as Integrated Design Environment and Integrated Debugging Environment) An IDE is a type of computer software that assists computer programmers in developing software. IDEs normally consist of a source code editor, a compiler and/or interpreter, buildautomation tools, and (usually) a debugger. Sometimes a version control system and various tools to simplify the construction of a GUI are integrated as well.1 Example IDEs that you might have already encountered are Microsoft Visual Studio .NET, Tasking and Eclipse. In this course, you will be developing software using the Freescale CodeWarrior IDE. Project A large software application will normally consist of a collection of source files, together with libraries and object codes that are collected from a variety of locations and developed by various developers. The application may also be configured to run on different targets, requiring different compilations. To support the development of such large applications, the concept of Project is introduced. A project forms the collection of files (of various types) that constitute an application, together with configuration information on how the files are to be compiled and linked to form the final product.

In this section, you will get familiar with the tools necessary to develop C applications for the MCF5213 microcontroller. You will create a simple project that will only interact with the user via standard I/O. (the PC screen and keyboard). 1. Run the Freescale CodeWarrior IDE (Integrated Development Environment) program a. Select start programs Freescale CodeWarrior CodeWarrior ColdFire V6.3 Freescale CodeWarrior IDE for

b. For convenience, you might want to create a shortcut of the IDE onto your desktop. 2. Once running, the IDE loads any previous projects that were left open when the IDE was last closed. It is perfectly safe to load and work on more than one project at one time. However, in order to eliminate confusion in this introductory tutorial, we will close all currently open projects and start with an empty environment. a. Close all open windows, including the so-called Project window. The IDE will in the end look as follows:

Reference: Wikipedia, http://en.wikipedia.org/wiki/Integrated_development_environment

Programming with CodeWarrior IDE 02/11/2006

3. We will now use the project wizard to help us create a C program, specific for the M5213EVB board which contains a MCF5213 microcontroller. a. Select File New from the top menu. b. A dialog box appears. From the Project frame, select ColdFire Stationery. c. Define the Project name and its Location. 1. Project name: sample 2. Location: Choose your own location! Note that the wizard automatically names the final folder destination to match that of the project name. This is for your convenience only, and you can choose any folder name desired. d. Select OK e. You are now prompted to select a project Stationery 1. You will be developing code for the 5213 microcontroller. Click on the + sign to the left of CF_M5213EVB to further expand its submenu. 2. You will be developing C code. Select C from the submenu that appears. 3. Are you sure M5213EVB? you selected the right microcontroller?

Programming with CodeWarrior IDE 02/11/2006

4. Select OK. 4. The wizard now creates the necessary files and configurations to help you start with a simple application. 5. Now is a good time to see what the wizard has done to your file system. a. Go to the file location where you specified the project to be created. b. Browse through the various directories and files created under this directory c. Dont be afraid to open any of them! Any interesting files? 1. the .mcp file is your project file containing all the necessary information about your project. Double-clicking on this file will open your project in CodeWarrior. 2. Under the Source directory, you will see a collection of C source code files! (Surprise! Surprise!) Most interesting is the main.c file that you will encounter very shortly. Double click on it anyway and see what it contains! 3. The Include directory contains many support source code files that you might find useful if you need to use any of the modules of the microcontroller such as PWM, ADC, timers, etc. 6. Back to the CodeWarrior IDE! A new window (the project window) appears showing two important components of your project: (1) The list of files constituting your projects and (2) the list of targets onto which the application will be built.

Programming with CodeWarrior IDE 02/11/2006

Target list

Debug Make

Project files Target options

a. Files - The files are categorised into different groups such as Source, Linker Command Files, etc. The location of the project files in these groups does not affect the functionality of the IDE, and is only advantageous for you to stay in control and understand the different types and categories of files involved. 1. Under the Source group, you will find a main.c file. Open this file by double-clicking on it. 1. Does it look familiar? 2. What do you think the program will do when it runs? 2. Under the Linker Command Files group, you will see two linker configuration files that specify how the files are to be built and linked together. 3. Under the Support files group, you will see a list of files of various types such as C-source code files and assembler code (files with the .s extension) The files are automatically created by the Project wizard to initialize your hardware appropriately depending on the options you selected. In most cases, you will not need to modify any of these files but it is important to be aware of their presence, and ensure that they are not deleted by mistake. 4. The Runtime, FP, C, and UART lib group contains a list of default library files that you will most likely need during development. 5. Try to create a new Group called Extra files!

Programming with CodeWarrior IDE 02/11/2006 b. Targets - Four different target configurations are specified by default. These targets can be individually configured for different usages. It is the first two targets that will be used in this tutorial. 1. M5213EVB Console Debug - This is the very basic stationery that outputs to the CodeWarrior's console window. The application is loaded onto SRAM. 2. M5213EVB UART Debug - This is the very basic stationery that outputs to the UART. User need to connect the terminal to see the output. The application is loaded onto SRAM. 3. M5213EVB UART Release - This is the very basic stationery that outputs to the UART. User need to connect the terminal to see the output. The application is loaded onto SRAM. 4. M5213EVB Internal ROM - This program copies the data from ROM to SDRAM. This is the very basic stationery that outputs to the UART. User need to connect the terminal to see the output. c. You will not need to change any of the configuration options for this tutorial, but it is important that you are familiar with the various possibilities that can be performed. In future projects, it may be necessary to modify certain properties. 1. Click on the Target Options Setting button , and browse through the set of options you can specify. Note that the options you specify only apply to the target you have currently selected. In this way, you can provide different configuration possibilities for different targets. 2. From the left menu, select the Target Access Paths category. In the right menu, you will see the list of paths that the system searches to find any included header files for your applications. (It is almost guaranteed that you will need to change this option in the near future.) 3. From the left menu, select the Debugger Remote Debugging category. Make sure that the Connection option is set to PEMICRO_USB. 4. Select OK. 7. Now, let us try to compile and make the project. What is the difference between Compile and Make/build? a. First, make sure that you choose the M5213EVB Console Debug target. b. Click on the Make button in the Project window. (alternatively, select Project Make from the top menu)

Programming with CodeWarrior IDE 02/11/2006 8. If everything is as it should be, and the compiler didnt find any problems, your system will be ready to run. We are hence ready to execute the program. a. Power your evaluation board. b. Run the debugger by clicking on the Debug button in the Project window. (alternatively, select Project Debug from the top menu) c. The program will first be downloaded onto your target, and a new debug window is loaded. Run

Kill Thread Step Over Step Into

d. The debugger is now waiting for instructions to execute and monitor your program. You can choose to execute the program to termination, or to step through it one instruction at a time. Move your mouse over (do not click) each of the top buttons illustrated above and read what they try to do. e. For now, we want to run the program to termination, by clicking on the Run button. 1. What do you observe? 2. Does the program behave like you expected? f. Once youre satisfied with your simple observation, terminate the execution by clicking on the Kill Thread button. g. If you simply try to close the debugger window, you will get a warning that there exists a running process that is currently being controlled by the debugger. You will be given the option to immediately Kill the process or Resume execution. Unless it is necessary, try not to kill the process in this way. h. Can you explain why did you have to terminate the program manually yourself? Why didnt the program terminate by itself once it was finished executing?

Programming with CodeWarrior IDE 02/11/2006 9. Now, we will try to compile and make the project for another target M5213EVB UART Debug a. Choose the M5213EVB UART Debug target. b. Repeat the above steps to make and debug the application 1. What do you observe? 2. Does the program behave like you expected? 3. Where did the output you expected go? 10. The answer to the above question is that the new target is configured so that the standard output is sent onto UART, instead of a window console within the CodeWarrior IDE. In order to obtain the output, we need to run a Windows HyperTermial. a. From the Windows Start menu, Programs accessories Communications HyperTermial program. b. Give the terminal a name (for example: CodeWarrior Output) c. Set the Connect Using property to COM1 d. Select Ok e. Set the properties as follows: Bits per second 19200 (baud rate) Data bits Parity Stop Bits Flow Control 8 None 1 None Run

11. Now, rerun the project in CodeWarrior and observe the hyperTerminal you setup. Do you observer any difference? a. Troubleshooting: You do not see any output in the terminal? 1. Make sure that the serial cable is connected to the UART0 terminal on your evaluation board 2. Make sure that the same serial cable is connected to the end of the PC 3. Make sure that you have selected to right COM terminal (COM1) b. Once youre satisfied with your observation, terminate the execution by clicking on the Kill Thread button.

Programming with CodeWarrior IDE 02/11/2006 c. You can also close the HyperTermial window. You will be prompted to save your connection! This can be useful so that you do not need to reconfigure your terminal every time you run HyperTermial. You can simply load your saved connection. 12. C programming in Codewarrior is simply like any other C programming! In order to refresh your C programming skills, you need now to modify the program to help the user guess a random number you choose between 1 and 100 a. Choose the M5213EVB Console Debug target. b. Use the fgets C-function to obtain the secret number from you. (Make sure that the user is not looking over your shoulder!) 1. Tip1: Calling the instruction fgets(line, sizeof(line), stdin) ;where line variable is defined as char line[100], waits until the user enters text into standard input (the keyboard), and saves the text entered into the line variable. 2. Tip2: Calling the instruction sscanf(line, "%d", &value) ;where value is defined as int value, scans the line array until it meets a non-digit and reformats the result as a digital number, placing the result in the value variable. c. Now, prompt the user to enter their guess of the number. d. If their guess is correct, write a Congratulation! message on standard output telling them of the result. Terminate the program. e. If their guess is larger or smaller than your random number, write a polite message telling them of their mistake (indicate whether it was larger or smaller) and give them an opportunity to guess again. Repeat steps C to E until the guess is correct. Hopefully, by the end of this section, you have become familiar with the CodeWarrior IDE and can use it to create simple C applications that can interact with the user. So far, the application user has been interacting with the embedded system through the PC standard input/output devices. This is satisfactory in certain cases such as during application development and debugging. However, in most embedded applications, there will be no attached PC to which the microcontroller can communicate. User interaction will hence be limited to I/O units such as a small keyboard, switches, LEDs and a simple LCD display. More importantly, I/O interactions with the microcontroller are not limited to user interactions. Another kind of relevant I/O devices that the microcontroller needs to interact with is the mechanical/electrical system that ought to be controlled. This interaction occurs via sensors and actuators. The next sections will introduce the available I/O devices attached to the system:

10

Programming with CodeWarrior IDE 02/11/2006 Part C will focus on the very basic modules that come with the microcontroller to illustrate its fundamental mechanisms. Part D will focus on drivers for additional I/O devices such as the LCD display, keyboard and motor control and sensors.

11

Programming with CodeWarrior IDE 02/11/2006

3 Part C MCF5213 Modules Introductions

In this section, we will introduce some of the relevant modules of the MCF5213 that you will encounter in this course. We will simply focus on two main modules of the microcontroller: General purpose I/O (GPIO) External interrupts (EPORT)

After this tutorial, you will not have to directly work with these modules at the register level, since drivers will be provided to control the I/O devices. It is however extremely important to be aware of the mechanisms behind these drivers, in order to be aware of their limitations and capabilities, and to know how handle any problems you encounter with them. (You will have problems with them. That we can promise!) We will further develop on the generic project developed in part B of this tutorial. For each of the subsections below, you would need to: 1. Create a new project as illustrated above. (An alternative is to simply copy the COMPLETE project directory onto another desired location. It is hence also convenient to rename the .mcp file under the top directory to reflect your new project description.) 2. Modify the main.c file as required.

3.1 General Purpose I/O

Many of the pins of the microcontroller may be used for several different functions. When not used for their primary function, many of the pins may be used as generalpurpose digital I/O pins. The digital I/O pins are grouped into 8-bit ports. (Note however that some ports do not use all 8 bits.) Each port has registers that configure, monitor and control the port pins. The figure below is a block diagram of the MCF5213 ports showing each port/pins primary as well as alternate functions.

12

Programming with CodeWarrior IDE 02/11/2006

To experiment with general purpose I/O functionality we will experiment with the 4 LEDs that are setup on the evaluation board. These 4 pins are connected to the TC port of the microcontroller, and we will hence develop the code necessary to configure this TC port. 1. Before we can output on these pins, we need to configure them for I/O output. a. The register MCF_GPIO_PTCPAR (Port Assignment Register), shown below, allows each pin to be configured between the GPIO function and its primary function (in this case, the TC ports primary function is a Digital Timer Input)

i. Setting MCF_GPIO_PTCPAR[0,1] to the bit values 00 configures PTC[0] as GPIO. (A setting of 01 is used for the primary function) ii. Setting MCF_GPIO_PTCPAR[2,3] to the bit values 00 configures PTC[1] as GPIO. (A setting of 01 is used for the primary function) iii. ...

13

Programming with CodeWarrior IDE 02/11/2006 b. In the main function of your project, write a simple instruction to set the register MCF_GPIO_PTCPAR such that the pins PTC[0], PTC[1], PTC[2] & PTC[3] act as GPIO. i. Dont forget to add #include common.h to the top of the file in order to obtain the macro definitions of MCF_GPIO_PTCPAR, as well as the other registers. c. We now need to set the pins directions to output. The register MCF_GPIO_DDRTC (Data Direction Register), shown below, controls the direction of the port TC when configured for GPIO functionality.

i. Setting MCF_GPIO_DDRTC[0] to the bit value 1 configures PTC[0] as GPIO output. ii. Setting MCF_GPIO_DDRTC[1] to the bit value 1 configures PTC[1] as GPIO output. iii. d. In the main function of your project, write a simple instruction to set the register MCF_GPIO_DDRTC such that the pins PTC[0], PTC[1], PTC[2] & PTC[3] act as output pins. 2. We are now ready to output the desired value on the output port TC. This value will then be reflected in the LEDs of the evaluation board. a. Outputting data on a GPIO output port is performed by simply writing the desired value onto the MCF_GPIO_PORTTC register. b. In the main function of your project, write a simple instruction to set the register MCF_GPIO_PORTTC such that the TC port (and hence the LEDs) represent the value, say, 4. c. What do you observe on the LEDs? Do they reflect the expected value? d. Now experiment with outputting different values such as: 0, 15, 23, etc. Can you make any interesting observations? e. You have so far outputted a data value on the complete TC port. Can you modify your code so that you can output on a specific pin of the TC port (for example PTC[2]) the bit value 1,without affecting the existing output on the remaining pins? i. Tip1: How do you set a single pin of a register to 1, without affecting the remaining bits?

14

Programming with CodeWarrior IDE 02/11/2006 1. If R is an 8 bit register with a binary value R=hgfedcba and I simply want to replace the e with 1, then R=R|00010000 will do the trick. Can you see why? ii. Tip2: How do you set a single pin of a register to 0, without affecting the remaining bits? 1. If R is an 8 bit register with a binary value R=hgfedcba and I simply want to replace the e with 0, then R=R&11101111 will do the trick. Can you see why?

3.2 External Interrupts

The MCF5213 edge port module (EPORT) supports 7 external interrupt sources on the NQ port. The 7 pins of this port can be used to handle external interrupts from various sources such as push buttons. The MCF5213EVB evaluation board comes with two user switches that are available for application as needed: SW1 is connected to the PNQ[4] pin and SW2 is connected to the PNQ[5] pin. 1. First, we need to configure these pins as external interrupt pins. Luckily, this has already been configured as part of the default project created for us. a. Open the file sysinit.c and look at the function mcf5213_allow_interrupts. Can you understand what this function does? That is the MCF_GPIO_PNQPAR and MCF_INTC_IMRL registers. i. Refer to the Reference manual and try to understand what each of the registers (MCF_GPIO_PNQPAR, MCF_INTC_IMRL, etc) do. ii. Maybe this is also the right opportunity to experiment with the debugging facilities of the system. 1. Create a breakpoint somewhere mcf5213_allow_interrupts function. in the

2. Start the debugger and wait until the program stops at your breakpoint. a. The debugger does not stop at breakpoints setup in the mcf5213_allow_interrupts function. The reason for this seems to be that the function is executed before the main function starts, and the debugger gives control to the user once at the start of the main function. Not earlier. b. An alternative is to setup the breakpoint early in the main function. The user can still view the registers setup in the mcf5213_allow_interrupts function then.

15

Programming with CodeWarrior IDE 02/11/2006 3. Select View registers from the top menu. A new window appears with a hierarchical list of the complete set of system registers. 4. Search for the registers used mcf5213_allow_interrupts function. in the

5. Now step through your program while observing how these registers are modified. Do these register get the values you expect them to? b. Now we need to specify what functions to execute whenever the external interrupts PNQ[4] and PNQ[5] occur. i. The following code is used to specify that function sw1_handler is to execute whenever the external interrupt PNQ[4] occurs: mcf5xxx_set_handler(64 + 4, sw1_handler); ii. Note that 64 is an offset necessary to place the function handler in the correct location in the interrupt vector table. iii. We also need to enable the interrupt request handlers using the following code segment: mcf5xxx_irq_enable(); iv. In the main function of your project, write the above code instructions. v. Finally, we also need to provide the sw1_handler function, and this function needs to look as follows: __interrupt__ void sw1_handler (void) { printf("You pressed SW1 button\n\r"); fflush(stdout); MCF_EPORT_EPFR = MCF_EPORT_EPFR_EPF4; //Acknowledge that the interrupt is handled } vi. Can you guess what this function will do when you press the SW1 button? vii. Write the above function in your project. viii. Make and execute your program. 1. You will receive errors complaining that the function mcf5xxx_set_handler is not defined! This is due to a bug in the project wizard. a. If you open the file mcf5xxx.c, you will see at the bottom of the file that the function

16

Programming with CodeWarrior IDE 02/11/2006 mcf5xxx_set_handler is defined! Why does CodeWarrior not find it? b. In the Project window, select the Link Order frame. You will notice that not all files included in your project are actually defined to be also linked during Make to form the final executable. Compare the files listed under Link Order to those listed under the Files frame! Makes sense? c. To handle this problem i. In the Link Order frame, right-click within the window and select Add Files. ii. A file browser appears. iii. Go to the directory location of your project. iv. Go to the Source subdirectory. v. Select ALL .c AND .s files vi. Select OK vii. You will receive some error messages from CodeWarrior! Ignore them for now! viii. Repeat the steps above and also include the files Source\clock\clock.c and Source\uart\uart.c d. One more problem need to be fixed. i. In the project directory, under the cfg subdirectory replace the existing M5213EVB_SRAM.lcf file with the one attached with this mail! e. You program should now be error free!!!!!! 2. Does the program behave as expected when you press the SW1 button? ix. Modify the code to setup the interrupt handler for PNQ[5] x. Make and execute the progam 1. Still operating as desired? xi. Can you modify the program so that the LED we developed earlier do something interesting whenever you switch the buttons SW1 & SW2?

17

Programming with CodeWarrior IDE 02/11/2006

4 Part D - Additional I/O devices

In this course, you will be using the additional I/O devices: LCD display 2 switches 2 motor controllers 2 motor encoders An 8-bit LED array

You will not need to understand the internal working of these devices and their configuration setup with the evaluation board. Instead, you will interact with the edvices using the appropriate driver. In this section, we will here introduce the driver for each of these devices.

To be continued in the next tutorial!

18