AGH University of Science and Technology Cracow Department of Electronics Microcontroller Lab Tutorial 1 Microcontrollers programming in C Author: Paweł Russek http://www.fpga.agh.edu.pl/ml ver. 3.10.16 1/18
1. Objectives In this tutorial, student will learn the distinctive elements of C programming language that are essential in microcontrollers programming. However, it is assumed that student already has some understanding of how to program in C language. Also, it will be introduced the FRDM-KL25Z evaluation board and its heart, the Kinetis KL25Z128VLK4 microcontroller from the NXP semiconductor company. Here, will focus on the microcontroller general purpose input/output peripheral. Additionally, after completing the tutorial, the student will know how to use Keil uvision5 software development environment to create a program code for the microcontroller, compile, and run the application. 2. C-language for microcontrollers 2.1. Hexadecimal notation Values that appear in program codes for microcontroller are most often expressed in hexadecimal notation. The hexadecimal value (also called base 16, or hex value) is a positional numeral system with a radix, or base, of 16. It uses sixteen distinct symbols, most often the symbols 0 9 to represent values zero to nine, and A, B, C, D, E, F (or a, b, c, d, e, f) to represent values ten to fifteen. In C program, they appear as string of digits in range from 0 to F that with the 0x prefix. For example: 0xC2, 0x2ad1, etc. The value conversion from hexadecimal to decimal numbers (and vice versa) is necessary very rare in practice. However, please, ensure you are familiar how to do it. More often it is necessary to convert binary to hex and hex to binary. That is straightforward if you know that each hexadecimal number corresponds directly to the distinct 4-bit binary. 0 1 2 3 4 5 6 7 8 9 A B C D E F 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 1101 1110 1111 Now, it is possible to convert between hex and bin by the simple number decomposition into digits: 0x9ABC 9 A B C 1001 1010 1011 1100 0b1001101010111100 Exercise 1.2 A. Convert to binary value: 0xAD, 0x23B B. Convert to hexadecimal value: 0b11011011, 0b1000100111 2.2. Data types for Embedded systems in C99 standard In general C programming textbooks we see char, short, int, long, data types. The int data type usually represents for the native data size of the processor. For example, it is a 2-byte size data 2/18
for a 16-bit processor and a 4-byte size data for a 32-bit processor. This may cause confusion and portability issue. Furthermore, whether char is signed or unsigned by default varies from compiler to compiler. The C99 standard, which is common for microcontrollers programming, addressed the issue by creating a new set of variable types. In ISO C99 standard, a set of data types were defined with number of bits and sign clearly defined in the data type names. Data type Size Range int8_t 1 byte -128 to 127 uint8_t 1 byte 0 to 255 int16_t 2 byte -32,768 to 32,767 uint16_t 2 byte 0 to 65,535 int32_t 4 byte -2,147,483,648 to 2,147,483,647 uint32_t 4 byte 0 to 4,294,967,295 2.3. Bit-wise Operations in C One of the most important and powerful features of the C language is its ability to perform bit manipulations. While every C programmer is familiar with the logical operators AND (&&), OR ( ), and NOT (!), many C programmers are less familiar with the bitwise operators AND (&), OR ( ), EX-OR (^), inverter (~), shift right (>>), and shift left (<<). These bit-wise operators are widely used in software engineering for embedded systems and control. Bitwise operations for the byte-bounded arguments are performed bit-by-bit for each pair of bits separately. For example: 0x54 & 0x0F results in0x04 // ANDing 0x40 0x86 results in 0xC6 // Oring 0x54 ^ 0x78 results in 0x2C // XORing ~ 0x55 results in 0xAA //Inverting 0x55 Consequently, OR can be used to set a bit, AND can be used to clear a bit, and XOR can be used to toggle a bit. For example: VAR1=VAR1 0x01 //Sets bit b0 in VAR1 variable VAR2=VAR2 0x08 //Sets bit b3 in VAR1 variable VAR3=VAR3&(~0x04) //Clear bit b2 in VAR3 variable VAR4=VAR4^0x80 //Toggle bit b7 in VAR4 variable Also, there are two bit-wise shift operators in C. Shift Right (>>) - shifts data a selected number of bit-positions to the right. Shift Left (<<) - shifts data a selected number of bitpositions to the left. For example: VAR1=0x01<<3 //VAR1=0x08 VAR1=0xD7>>2 //VAR1=0x35 3/18
Now, you can combine the bitwise and shift operations to easily manipulate bits of the variables. For example: VAR1=VAR1 (1<<5) //Sets bit b5 VAR2=VAR2 & ~(1<<7) //Clears bit b7 VAR3=VAR3 ^ (1<<3) //Toggles bit b3 Bitwise operation can be also used in compound statements (like VAR=VAR+1 is equivalent to VAR+=1). For example: VAR1 = (1<<5) //Sets bit b5 VAR2&= ~(1<<7) //Clears bit b7 VAR3^= (1<<3) (1<<6)//Toggles bits b3 and b6 2.4. Pointer handling If you're going to master microcontroller programming in C, you need to excel in pointer manipulations. As you probably remember, the C pointer points to a location in the memory. However, as today's computers runs Operating Systems, which protects the physical computer memory from direct user program manipulations, values kept in pointers are not directly set by the OS programmers. It is different in microcontroller programming, where the memory space can be accessed straightforwardly. Here, you may want to manipulate the value of the certain memory address. For example: uint32_t* mem_addr = 0xFFFF2000; //Declares the pointer to access address 0xFFFF2000; *mem_addr = 0xBA8A0070; //Sets the value of 0xBA8A0070 at location 0xFFFF2000; The above two lines of code can be repleaced by the following single line like this: *((uint32_t*) 0xFFFF2000)= 0xBA8A0070; You may also like to write in the different way, which is the same for the compiler but seems to be more clear coding style : #define MY_MEM_LOCATION *((uint32_t*) 0xFFFF2000) MY_MEM_LOCATION=0xBA8A0070; //Sets the value of 0xBA8A0070 at location 0xFFFF2000 MY_MEM_LOCATION =(1<<27); //Sets bit b27 at location 0xFFFF2000; MY_MEM_LOCATION&=~((1<<4) (1<<23)); //Clears bits b4 and b23 at location 0xFFFF2000; 2.5. Infinite loop In microcontroller programming, the infinite loop that is included in a program code is essential. When the microcontroller does not run the operating system, the user application must not exit at any time because that would lead to the system crash. Therefore, microcontrollers' software developers always include infinite loops in their codes. If you develop your application with no control of the operating system you experience so called bare metal programming. 4/18
Example of the infinite loop in C: main(){ } /* One-time run code */ while(1){ }; 2.6. Volatile keyword /* Program code for infinite loop */ In C programming a variable declared with the volatile keyword usually has special properties related to optimization. Generally speaking, the volatile keyword is intended to prevent the compiler from certain optimizations. The volatile keyword indicates that a value may change between different accesses, even if it does not appear to be modified. We will use the volatile keyword to indicate hardware registers to the compiler. If the compiler knows that the certain address is not a memory it never tries to removes unnecessary code. Example: #define MY_MEM_LOCATION *((uint32_t*) 0xFFFF2000) main(){ } MY_MEM_LOCATION=0x55555555; while(1); In the above code, the MY_MEM_LOCATION variable is never read, so the compiler might want to remove unnecessary assignment to it. #define MY_MEM_LOCATION *((volatile uint32_t*) 0xFFFF2000) main(){ } MY_MEM_LOCATION=0x55555555; while(1); After adding volatile no optimization take place. More cases that require the volatile keyword exist, but we stop here, as further discussion is beyond our introductory tutorial. 3. ARM Cortex-M0+ KL25Z128VLK4 is a microcontroller form the NXP semiconductor company that features the CPU which is well-known and widely used ARM's Cortex-M0+ architecture. The KL25Z128VLK4 chip has 128K bytes (128KB) of on-chip Flash memory for code, 16KB of onchip SRAM for data, and a large number of on-chip peripherals. 5/18
Kinetis L Series KL2x Microcontrollers block diagram ARM is 32-bit microprocessor, and it has 4GB (Giga bytes) of memory space. It also uses memory mapped I/ O meaning the I/ O peripheral ports are mapped into the 4GB memory space. Memory Map in KL25Z128VLK4 micrcontroller 128KB of Flash memory is used for program code. The 16KB SRAM is for variables and program stack. The peripherals such as I/ Os, Timers, ADCs are mapped to addresses starting at 0x40000000. 4. GPIO (General Purpose IO) While memory holds code and data for the CPU to process, the I/O ports are used by the CPU to access input and output devices. Microcontrollers always offer so called General Purpose I/ O (GPIO) that are used for binary input/output devices such as LEDs, switches, LCD, keypad, and so on. In NXP ARM chips, I/ O ports are named with alphabets A, B, C, and so on. Each port can have up to 32 pins and they are designated as PTA0-PTA31, PTB0-PTB31, and so on. It must be noted that not all 32 pins of each port are implemented. The ARM chip used in FRDM board is in Kinetis L series with part number KLxxZ128VLK4. It has ports A, B, C, D, and E. 6/18
KL25Z128VLK4 pinout The GPIO ports addresses assigned to the PTA-PTE as follow: GPIO Port A GPIO Port B GPIO Port C GPIO Port D 0x400F F000 0x400F F040 0x400F F080 0x400F F0C0 GPIO Port E 0x400F F100 There are many registers associated with each of the above GPIO ports and they have designated addresses in the memory map. The above addresses are the Base addresses meaning that within that base address we have many registers associated with that port, as we will see next. Generally every microcontroller has minimum of two registers associated with each GPIO port. They are Data Register and Direction Register. The Direction register is used to make the pin either input or output. After the Direction register is properly configured, then we use the Data register to actually write to the pin or read data from the pin. It is the Direction register (when configured as output) that allows the information written to the Data register to be driven to the pins of the device. 7/18
The basic GPIO structure (simplified description) The Port Data Output Register (GPIOx_PDOR) is located at the offset address of 0x0000 from the Base address of the port in the microcontrollers of the Kinetis L family. Similarly, the address of the GPIO Direction register (GPIOx_PDDR) is located at the offset address of 0x0014 from the Base address of that port. The Direction register bit needs to be a 0 to configure the port pin as input and a 1 as output. 4.1. Alternate pin functions Each pin of the Freescale ARM chip can be used for one of several functions including GPIO. We choose the function by programming a special function register (SFR). Using a single pin for multiple functions is called pin multiplexing and is widely used by microcontrollers. In the 8/18
absence of pin multiplexing, a microcontroller will need several hundred pins to support all of its on-chip features. For example, a given pin can be used as simple digital I/ O (GPIO), analog input, or I2C pin. Of course not all at the same time. We must make sure that a pin is assigned to only one peripheral function at a time. The PORTx_PCRn (Portx Pin Control) special function register allows us to program a pin to be used for a given alternate function. It must be noted that each pin of ports A-E has its own PORTx_PCRn register. The x is used for Ports A to E and n is used for pin number 0 to 31. As we mentioned earlier, each port of A to E can have up to 32 pins. At the moment we will focus on the 3-bit MUX field. To use a pin as simple digital I/ O, we must choose MUX = 001 option. The PCR ports addresses assigned to the PTA-PTE as follow: PORTA base address PORTB base address PORTC base address PORTD base address 0x4004_9000 0x4004_A000 0x4004_B000 0x4004_C000 9/18
As we highlighted each pin of ports A-E has its own PORTx_PCRn register. To calculate the address of the particular pin register we calculate PORTx base address + (4 n), where n=0 to 31 For example the address of PORTB_PCR18 is 0x4004_A000 + (18 4) = 0x4004_A000 + (0x12 << 2) = 0x4004_A048 Exercise 4.1 Fill the table below with the corresponding registers' addresses Register name GPIOB_PDOR GPIOB_PDDR PORTB_PCR18 PORTB_PCR19 Address 5. System clock gating The System Clock Gating Control Register 5 (SIM_SCGC5) is used to enable the clock source for the I/ O port circuitry among other things. If an I/ O port is not used, the clock source to it can be disabled in order to save power. There is only one SIM_SCGC5 special function register for all the GPIO ports and some of the bits of this register are used to enable the clock source to Ports A to E. For example, to enable the clock source to PTB, we need to set HIGH the b10 of the SIM_SCGC5 register. We can OR hex value 0x400 (0b0100 0000 0000) with SIM_SCGC5 register to make sure it leaves clock source to other ports unchanged: SIM_SCGC5 =(1<<10); 10/18
6. FRDM-KL25Z development board The Freescale Freedom KL25Z board, FRDM-KL25Z, is a capable and cost-effective design featuring a Kinetis L MKL25Z128VLK4 microcontroller. The pins on the KL25Z microcontroller are named for their general purpose input/output port pin function. For example, the 1st pin on Port A is referred to as PTA1. The I/O connector pin names of FRDM- KL25Z are given the same name as the KL25Z pin connected to it, where applicable. 6.1. LED connection in Freescale FRDM board In the Freescale Freedom board we have a tri-color RGB LED connected to PTB18 (red), PTB19 (green), and PTD1 (blue). LED connection to PTB and PTD Freescale FRDM board 11/18
7. Getting started with Keil uvision5 software At last, we can start the software development environment to run our very first microcontroller program. We will use Keil uvision5 software in microcontrollers laboratory. The uvision 5 is environment made by Keil (ARM) and is designed for programming and debugging microcontrollers based on ARM architecture. Exercise 7.1 Run uvision5 and create a new project for MKL25Z128VLK4 microcontroller. 1. On your PC, click twice on uvision icon placed both on desktop and in Menu Start: 2. Choose Project -> New uvision Project from menu 2. Note. It is recommended to place your project in a newly created directory that is called afte your name. Also, for your own convinience, place each new project in a separate sub-directory. 3. Create and select the destination path my_name/rgb_led for a new project. Afterwards, call your project rgb_led. You should get C:\MDK-ARM\my_name\rgb_led\rgb_led.uvproj 4. The next step is to select a microcontroller you will work with. Select MKL25Z128xxx4 12/18
5. Next, you should select the basic libraries necessary to run any application. We need the startup code and core configuration routines for the CPU. Check the select boxes for CMSIS- >CORE, and Device->Startup. Next, when you click OK, the main uvision widow appears. 6. Please find the startup codes in the Project window. 5. Right click the Source Group folder and select Add new item to group.... Create a new source file main.c. Click Add. 6. Copy and paste the code given below to the main.c file. /*----------------------------------------------------------------------------- * Name: main.c * Purpose: RGB LED experiments for FRDM-KL25Z board * Author: Student *----------------------------------------------------------------------------*/ #include "MKL25Z4.h" /*Device header*/ 13/18
#define RED_LED_POS 18 #define GREEN_LED_POS 19 #define BLUE_LED_POS 1 #define SCGC5 (*((volatile uint32_t*)0x????????)) #define PDOR (*((volatile uint32_t*)0x????????)) #define PDDR (*((volatile uint32_t*)0x????????)) #define PCR19 (*((volatile uint32_t*)0x????????)) void delayms( int n) { int i; int j; for( i = 0 ; i < n; i++) for(j = 0; j < 7000; j++) {} } int main() { SCGC5 =(1<<10); /* Enable clock for GPIO B */ PCR19 =(1<<8); /* Set pin 19 of PORT B as GPIO */ PDDR =(1<<GREEN_LED_POS); /* Set pin 19 of GPIO B as output */ while(1){ PDOR&=~(1<<GREEN_LED_POS); /* Turn on Green LED */ delayms(500); /* Wait */ PDOR =(1<<GREEN_LED_POS); /* Turn off Green LED */ delayms(500); /* Wait */ } } 7. Fill the addresses in the given code with addresses you completed in Exercise 4.1. 8. Compile the code. Press F7 or select Buld icon 9. Ensure that your code has been compiled with no errors. Check the log in the Build Output window. Look for:.\rgb_led.axf" - 0 Error(s) 8. Downloading binaries to FRDM-KL25Z Exercise 8.1 1. Connect FRDM-KL25Z to the USB port of your PC. Use OpenSDA port at the FRDM-KL25Z side. 14/18
OpenSDA is Freescale s name for ARM s CMSIS-DAP. This is an ARM standard that specifies an on-board debug adapter. The Freedom board incorporates CMSIS-DAP. 2. Select Options for Target or ALT-F7 and select the Debug tab. 3. Select CMSIS-DAP Debugger from the drop-down list. 4. Click on Settings and choose SW from Port list. 15/18
5. Additionally, select Reset and Run option in Flash Download tab. 6. Click OK twice to close Options for target window. 7. To download binaries to Kinetis microcontroller select Download icon 8. Observe the blinking green LED on your FRDM board. 9. "MKL25Z4.h" header file You might have found determining addresses of the control registers and defining them in your code very tedious. But do not worry. All the definitions you need to programme MKL25Z128VLK4 are already defined in MKL25Z4.h header file. You need only to learn how to use it. Look at the code below and see how our blinking led program looks then the header 16/18
definitions are incorporated. /*----------------------------------------------------------------------------- * Name: main.c * Purpose: RGB LED experiments using MKL25Z4 definitions * Author: Student *----------------------------------------------------------------------------*/ #include "MKL25Z4.h" /*Device header*/ #define RED_LED_POS 18 #define GREEN_LED_POS 19 #define BLUE_LED_POS 1 void delayms( int n) { int i; int j; for( i = 0 ; i < n; i++) for(j = 0; j < 7000; j++) {} } int main() { SIM->SCGC5 =(1<<10); /* Enable clock for GPIO B */ PORTB->PCR[19] =(1<<8); /* Set pin 19 of PORT B as GPIO */ GPIOB->PDDR =(1<<GREEN_LED_POS); /* Set pin 19 of GPIO B as output */ while(1){ GPIOB->PDOR&=~(1<<GREEN_LED_POS); /* Turn on Green LED */ delayms(500); /* Wait */ GPIOB->PDOR =(1<<GREEN_LED_POS); /* Turn off Green LED */ delayms(500); /* Wait */ } } As you probably notice, MKL25Z4 header incorporate pointers to the structures to help access registers within Kinetis L modules. There are used pointers to SIM, PORTB, and GPIOB structures in our example. Structures contain all registers of the given module. The '->' symbol is used to access elements of the structure that is given by a pointer. For example SIM->SCGC5 is used to access the SCGC5 register in the SIM module (System Integration Module). Similarly, GPIOB->PDDR is used to access the PDDR register in the GPIOB module. Etc. Notice, that PORTB_PCRn registers form an array PORTB->PCR. The array is indexed by the port bit numbers. For example PORTB->PCR[19] is a pointer to the PORTB_PCR19 register. If you are a C nerd, you like to dig for the corresponding definitions and declarations of the 17/18
structures in the MKL25Z4.h file. Exercise 9.1 Compile and run the new version (with use of MKL25Z4 header definitions) of the blinking green led code. Afterwards, modify the code to blink RED, GREEN, and BLUE led in the infinite sequence. Fee free to customize the blinking behaviour to your own taste. 18/18