AVR1000: Getting Started Writing C-code for XMEGA. 8-bit Microcontrollers. Application Note. Features. 1 Introduction



Similar documents
AVR1309: Using the XMEGA SPI. 8-bit Microcontrollers. Application Note. Features. 1 Introduction SCK MOSI MISO SS

AVR1318: Using the XMEGA built-in AES accelerator. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

AVR1301: Using the XMEGA DAC. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

AVR1600: Using the XMEGA Quadrature Decoder. 8-bit Microcontrollers. Application Note. Features. 1 Introduction. Sensors

AVR1900: Getting started with ATxmega128A1 on STK bit Microcontrollers. Application Note. 1 Introduction

AVR1510: Xplain training - XMEGA USART. 8-bit Microcontrollers. Application Note. Prerequisites. 1 Introduction

AVR033: Getting Started with the CodeVisionAVR C Compiler. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

AVR32701: AVR32AP7 USB Performance. 32-bit Microcontrollers. Application Note. Features. 1 Introduction

AVR353: Voltage Reference Calibration and Voltage ADC Usage. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

Using CryptoMemory in Full I 2 C Compliant Mode. Using CryptoMemory in Full I 2 C Compliant Mode AT88SC0104CA AT88SC0204CA AT88SC0404CA AT88SC0808CA

8-bit. Application Note. Microcontrollers. AVR282: USB Firmware Upgrade for AT90USB

AVR32138: How to optimize the ADC usage on AT32UC3A0/1, AT32UC3A3 and AT32UC3B0/1 series. 32-bit Microcontrollers. Application Note.

AVR1922: Xplain Board Controller Firmware. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

General Porting Considerations. Memory EEPROM XRAM

AVR319: Using the USI module for SPI communication. 8-bit Microcontrollers. Application Note. Features. Introduction

Application Note. 8-bit Microcontrollers. AVR270: USB Mouse Demonstration

AVR115: Data Logging with Atmel File System on ATmega32U4. Microcontrollers. Application Note. 1 Introduction. Atmel

AVR305: Half Duplex Compact Software UART. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

Atmel AVR4921: ASF - USB Device Stack Differences between ASF V1 and V2. 8-bit Atmel Microcontrollers. Application Note. Features.

AVR317: Using the Master SPI Mode of the USART module. 8-bit Microcontrollers. Application Note. Features. Introduction

Application Note. 8-bit Microcontrollers. AVR272: USB CDC Demonstration UART to USB Bridge

AVR2006: Design and characterization of the Radio Controller Board's 2.4GHz PCB Antenna. Application Note. Features.

AVR055: Using a 32kHz XTAL for run-time calibration of the internal RC. 8-bit Microcontrollers. Application Note. Features.

AVR32788: AVR 32 How to use the SSC in I2S mode. 32-bit Microcontrollers. Application Note. Features. 1 Introduction

Atmel AVR4920: ASF - USB Device Stack - Compliance and Performance Figures. Atmel Microcontrollers. Application Note. Features.

AVR287: USB Host HID and Mass Storage Demonstration. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

USER GUIDE EDBG. Description

AVR030: Getting Started with IAR Embedded Workbench for Atmel AVR. 8-bit Microcontrollers. Application Note. Features.

APPLICATION NOTE. Atmel AVR134: Real Time Clock (RTC) Using the Asynchronous Timer. Atmel AVR 8-bit Microcontroller. Introduction.

Application Note. 8-bit Microcontrollers. AVR293: USB Composite Device

AVR106: C functions for reading and writing to Flash memory. 8-bit Microcontrollers. Application Note. Features. Introduction

AVR1324: XMEGA ADC Selection Guide. 8-bit Atmel Microcontrollers. Application Note. Features. 1 Introduction

Atmel AVR4027: Tips and Tricks to Optimize Your C Code for 8-bit AVR Microcontrollers. 8-bit Atmel Microcontrollers. Application Note.

AVR1003: Using the XMEGA Clock System. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

AVR1321: Using the Atmel AVR XMEGA 32-bit Real Time Counter and Battery Backup System. 8-bit Microcontrollers. Application Note.

Application Note. C51 Bootloaders. C51 General Information about Bootloader and In System Programming. Overview. Abreviations

32-bit AVR UC3 Microcontrollers. 32-bit AtmelAVR Application Note. AVR32769: How to Compile the standalone AVR32 Software Framework in AVR32 Studio V2

8-bit Microcontroller. Application Note. AVR134: Real-Time Clock (RTC) using the Asynchronous Timer. Features. Theory of Operation.

AVR106: C Functions for Reading and Writing to Flash Memory. Introduction. Features. AVR 8-bit Microcontrollers APPLICATION NOTE

APPLICATION NOTE. Atmel AVR443: Sensor-based Control of Three Phase Brushless DC Motor. Atmel AVR 8-bit Microcontrollers. Features.

AVR245: Code Lock with 4x4 Keypad and I2C LCD. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

AT91SAM ARM-based Flash MCU. Application Note

AVR134: Real Time Clock (RTC) using the Asynchronous Timer. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

3-output Laser Driver for HD-DVD/ Blu-ray/DVD/ CD-ROM ATR0885. Preliminary. Summary. Features. Applications. 1. Description

Atmel AVR4903: ASF - USB Device HID Mouse Application. Atmel Microcontrollers. Application Note. Features. 1 Introduction

How To Use An Atmel Atmel Avr32848 Demo For Android (32Bit) With A Microcontroller (32B) And An Android Accessory (32D) On A Microcontroller (32Gb) On An Android Phone Or

AVR2004: LC-Balun for AT86RF230. Application Note. Features. 1 Introduction

AVR1306: Using the XMEGA Timer/Counter. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

AVR151: Setup and Use of the SPI. Introduction. Features. Atmel AVR 8-bit Microcontroller APPLICATION NOTE

8-bit Microcontroller. Application Note. AVR105: Power Efficient High Endurance Parameter Storage in Flash Memory

AVR125: ADC of tinyavr in Single Ended Mode. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

AVR32110: Using the AVR32 Timer/Counter. 32-bit Microcontrollers. Application Note. Features. 1 Introduction

AVR034: Mixing C and Assembly Code with IAR Embedded Workbench for AVR. 8-bit Microcontroller. Application Note. Features.

8051 Flash Microcontroller. Application Note. A Digital Thermometer Using the Atmel AT89LP2052 Microcontroller

8-bit Microcontroller. Application Note. AVR222: 8-point Moving Average Filter

Introducing a platform to facilitate reliable and highly productive embedded developments

APPLICATION NOTE. AT07175: SAM-BA Bootloader for SAM D21. Atmel SAM D21. Introduction. Features

8-bit RISC Microcontroller. Application Note. AVR236: CRC Check of Program Memory

8-bit Microcontroller. Application Note. AVR415: RC5 IR Remote Control Transmitter. Features. Introduction. Figure 1.

AVR32100: Using the AVR32 USART. 32-bit Microcontrollers. Application Note. Features. 1 Introduction

8-bit RISC Microcontroller. Application Note. AVR155: Accessing an I 2 C LCD Display using the AVR 2-wire Serial Interface

AT89C5131A Starter Kit... Software User Guide

8-bit Microcontroller. Application Note. AVR400: Low Cost A/D Converter

8-bit Microcontroller. Application Note. AVR286: LIN Firmware Base for LIN/UART Controller. LIN Features. 1. Atmel LIN/UART Controller

AVR223: Digital Filters with AVR. 8-bit Microcontrollers. Application Note. Features. 1 Introduction

SMARTCARD XPRO. Preface. SMART ARM-based Microcontrollers USER GUIDE

AT88CK490 Evaluation Kit

APPLICATION NOTE Atmel AT02509: In House Unit with Bluetooth Low Energy Module Hardware User Guide 8-bit Atmel Microcontroller Features Description

APPLICATION NOTE. Atmel AT04389: Connecting SAMD20E to the AT86RF233 Transceiver. Atmel SAMD20. Description. Features

AVR241: Direct driving of LCD display using general IO. 8-bit Microcontrollers. Application Note. Features. Introduction AVR

AT91 ARM Thumb Microcontrollers. AT91SAM CAN Bootloader. AT91SAM CAN Bootloader User Notes. 1. Description. 2. Key Features

Atmel AVR1017: XMEGA - USB Hardware Design Recommendations. 8-bit Atmel Microcontrollers. Application Note. Features.

Application Note. Atmel ATSHA204 Authentication Modes. Prerequisites. Overview. Introduction

AVR ONE!... Quick-start Guide. EVK Windows 32104B AVR ONE! 02/10

8-bit RISC Microcontroller. Application Note. AVR910: In-System Programming

8-bit RISC Microcontroller. Application Note. AVR182: Zero Cross Detector

AT89LP Flash Data Memory. Application Note. AT89LP Flash Data Memory API. 1. Introduction. 2. Theory of Operation. 2.1 Flash Memory Operation

AVR120: Characterization and Calibration of the ADC on an AVR. 8-bit Microcontrollers. Application Note. Features. Introduction

AVR127: Understanding ADC Parameters. Introduction. Features. Atmel 8-bit and 32-bit Microcontrollers APPLICATION NOTE

APPLICATION NOTE. Atmel AT02985: User s Guide for USB-CAN Demo on SAM4E-EK. Atmel AVR 32-bit Microcontroller. Features. Description.

AVR311: Using the TWI Module as I2C Slave. Introduction. Features. AVR 8-bit Microcontrollers APPLICATION NOTE

AVR131: Using the AVR s High-speed PWM. Introduction. Features. AVR 8-bit Microcontrollers APPLICATION NOTE

Step Motor Controller. Application Note. AVR360: Step Motor Controller. Theory of Operation. Features. Introduction

AT91 ARM Thumb Microcontrollers. Application Note. Interfacing a PC Card to an AT91RM9200-DK. Introduction. Hardware Interface

USER GUIDE. ZigBit USB Stick User Guide. Introduction

Application Note. Atmel CryptoAuthentication Product Uses. Atmel ATSHA204. Abstract. Overview

APPLICATION NOTE. Atmel LF-RFID Kits Overview. Atmel LF-RFID Kit. LF-RFID Kit Introduction

AVR315: Using the TWI Module as I2C Master. Introduction. Features. AVR 8-bit Microcontrollers APPLICATION NOTE

8-bit Microcontroller. Application Note. AVR201: Using the AVR Hardware Multiplier

APPLICATION NOTE. Secure Personalization with Transport Key Authentication. ATSHA204A, ATECC108A, and ATECC508A. Introduction.

8-bit Microcontroller. Application Note. AVR314: DTMF Generator

etpu Host Interface by:

256K (32K x 8) Battery-Voltage Parallel EEPROMs AT28BV256

How to Calculate the Capacitor of the Reset Input of a C51 Microcontroller 80C51. Application Note. Microcontrollers. Introduction

Application Note. USB Microcontrollers. USB PC Drivers Based on Generic HID Class. 1. Introduction

AT15007: Differences between ATmega328/P and ATmega328PB. Introduction. Features. Atmel AVR 8-bit Microcontrollers APPLICATION NOTE

APPLICATION NOTE. Atmel AT01095: Joystick Game Controller Reference Design. 8-/16-bit Atmel Microcontrollers. Features.

AN11008 Flash based non-volatile storage

Quick Start Guide. CAN Microcontrollers. ATADAPCAN01 - STK501 CAN Extension. Requirements

APPLICATION NOTE. Authentication Counting. Atmel CryptoAuthentication. Features. Introduction

Transcription:

AVR1000: Getting Started Writing C-code for XMEGA Features Naming conventions - Register names - Bit names C-code names - Bit and group masks - Group configuration masks Methods for accessing registers Methods for writing reusable module functions 8-bit Microcontrollers Application Note 1 Introduction Short development times and high quality requirements on electronic products has made high-level programming languages a requirement. The main reason is that High level languages make it easier to maintain and reuse code due to better portability and readability. The choice of programming language alone does not ensure high readability and reusability; good coding style does. Therefore the XMEGA peripherals, header files and drivers are designed with this in mind. The most widely used high-level language for AVR microcontrollers is C, and this application note therefore focuses on C programming. To support most of the AVR C compilers that are available the code examples are as far as possible written in ANSI C. A few examples are specific to IAR Embedded Workbench, but the ideas and methods can be used for other compilers with minor changes. IAR specific examples are clearly marked. Rev.

2 XMEGA Modules An AVR XMEGA is composed of several building blocks: An AVR CPU core, SRAM, Flash, EEPROM and a number of peripheral modules. These building blocks are called module types. An XMEGA can have one or more instances of a given module type. All instances of a module type have the same features and functions. Some module types can be a subset of other module types. These inherit a subset of the features (and registers) of the super type, all inherited features are fully compatible. This applies to e.g. timers and IO ports. The subset of a module type can for a timer mean that it has fewer compare and capture channels than a full timer module. Similarly, an IO port may have less than eight pins. A module type can be a USART, while the module instance is e.g. USARTC0, where the C0 suffix indicates the instance is USART number 0 on port C. For simplicity, a module instance will be referred to as a module throughout this document, unless there is a need to differentiate. Each module has a number of registers that contain control or status bits. All modules of a given type contain the same set (or subset) of registers, and all these registers contain the same set (or subset) of control and status bits. Figure 2-1. Module types, instances, registers and bits. Module Type MODULE0 Register Bit 0 Bit 7 MODULEn Register Each module has a fixed base address in the IO memory map and all registers contained in the module have fixed offset addresses relative to the module base address. This way each register will not only have an absolute address in the IO memory space, but also a relative address defined by its offset. The register offset addresses are equal for all instances of a module type, simplifying the task of writing drivers that can be used for all modules of a specific type. 2 AVR1000

2.1 Register Naming Convention 2.2 Bit Naming Convention AVR1000 Register are roughly speaking divided into control, status and data registers and the naming of registers reflect this. A general-purpose control register of the module is named CTRL. If multiple general-purpose control registers exists in a module they have a suffix character. In this case the control registers would be named CTRLA, CTRLB, CTRLC and so on. This also applies to STATUS registers. For registers that have a specific function the name reflects this functionality. For example, a control register that controls the interrupt level of a module is named INTCTRL. Since the AVR data bus width is 8 bit, larger registers are implemented using several 8-bit registers. For a 16-bit register, the high and low bytes are accessed by appending H and L respectively to the register name. For example, the 16-bit Timer/Counter count register is named CNT. The two bytes are named CNTL and CNTH. For a register larger than 16 bit, the bytes are numbered from the least significant byte. For example, the 32-bit ADC calibration register is named CAL. The four bytes are named CAL0, CAL1, CAL2 and CAL3 (from least to most significant byte). Most C compilers offer automatic handling of access to multi-byte registers. In that case the name CNT, without H or L suffix, could be used to perform a 16-bit access to the Timer/Counter count register. This is also the case for 32-bit registers. Register bits can have an individual function or be part of a bit group that have a joint function: An individual bit could be a bit that enables a module, e.g. the USART ENABLE bit. A bit group can consist of two of more bits that jointly select a specific configuration of the module that they belong to. A bit group offers up to 2 n selections, where n is the number of bits in the bit group. The two bits that control the USART Receive Complete interrupt level, RXINTLVL[1:0], is an example of a bit group. These two bits offer the following selections: Table 2-1. RXINTLVL bits and corresponding interrupt level selection. RXINTLVL1 RXINTLVL0 Interrupt level selection 0 0 Interrupt Off 0 1 Low level interrupt 1 0 Medium level interrupt 1 1 High level interrupt Bits that are part of a group will always have a number suffix. Bits that are not part of a bit group will never have a number suffix. A Timer/Counter control register D has two bit groups, EVACT and EVSEL. The bits in these groups have a number suffix, while the EVDLY bit, which is not part of a bit group has no number suffix. Table 2-2. Bits groups and bit names for bits in Timer/Counter Control register D CTRLD. Bit Group EVACT - EVSEL Bit name EVACT2 EVACT1 EVACT0 EVDLY EVSEL3 EVSEL2 EVSEL1 EVSEL0 Bit number 7 6 5 4 3 2 1 0 3

3 Writing C-code for XMEGA The following sections focus on how to write C-code for the XMEGA. The examples show how to make the code highly readable and portable between different XMEGA devices. The examples can also be used as a guideline to write code that is easy to verify and maintain. XMEGA modules are located in dedicated and continuous blocks in the memory space and can be seen as encapsulated units. This reflects on the way that the modules are accessed when coding C: modules are encapsulated using C structs, in which all module registers are contained. Figure 3-1 shows an illustration of this. Note that some registers have no direct module association. These are not encapsulated in structs, as the struct is used to associate registers with a module. For larger code projects the module structs provide advantages, not only to readability, but also because the compilers can reuse the module drivers and thereby make the code very compact. This is described in more details later. This document introduces a naming convention and register access methods that are different from what AVR programming veterans are used to, but one should be aware that the classic way to access registers is still supported by the header files. This also applies on the bit level. 4 AVR1000

Figure 3-1. Modules placed in dedicated blocks in IO memory space. IO memory space AVR1000 USARTC0 USARTC1 struct USART TCD0 TCD1 TCE0 struct TC SPIC0 struct SPI PORTA PORTB PORTC PORTD PORTE PORTF PORTG PORTH struct PORT 3.1 XMEGA Header Files A dedicated header file is available for each XMEGA device. If the target device is specified in the project settings (assuming that one uses the IDE for IAR EWAVR), the IAR compiler will automatically include the correct header file if the device file is included as shown in Code Listing 3-1. Code Listing 3-1. IAR header file inclusion. #include <ioavr.h> The advantage is that if the target device changes, there is no need to change the source files, only the project settings. 5

3.2 Modules Registers The IO map is laid out so that all registers for a given peripheral module are placed in one continuous memory block. Registers belonging to different modules are not mixed. This makes it possible to organize all peripheral modules in C structs, where the address of the struct defines the base address, of the module. All registers belonging to a module are elements in the module struct. An example is the Programmable Multi-level Interrupt Controller (PMIC) module. The struct declaration for this module is shown in Code Listing 3-2 and an example of its use in Code Listing 3-3. Note that the example in Code Listing 3-3 assumes that there is an instance of the PMIC_t type named PMIC. This is covered later in this document. Code Listing 3-2. Module struct declaration. typedef struct PMIC_struct { unsigned char STATUS; // Status Register unsigned char INTPRI; // Interrupt Priority unsigned char CTRL; // Control Register } PMIC_t; Code Listing 3-3. Module struct usage. unsigned char temp; temp = PMIC.STATUS; // Read status register into temp PMIC.CTRL = PMIC_PMRRPE_bm; // Set PMRRPE bit in control // register 3.2.1 Multi-word Registers in Module Structs Some registers are used in conjunction with other registers to represent 16 or 32 bit values. As example one could look at the ADC struct declaration shown in Code Listing 3-4. 6 AVR1000

AVR1000 Code Listing 3-4. ADC struct declaration. typedef struct ADC_struct { unsigned char CH0MUXCTRL; unsigned char CH1MUXCTRL; unsigned char CH2MUXCTRL; unsigned char CH3MUXCTRL; unsigned char CTRLA; unsigned char CTRLB; unsigned char REFCTRL; unsigned char EVCTRL; WORDREGISTER(CH0RES); WORDREGISTER(CH1RES); WORDREGISTER(CH2RES); WORDREGISTER(CH3RES); unsigned char reserved_0x10; unsigned char reserved_0x11; unsigned char CH0INTCTRL; unsigned char CH1INTCTRL; unsigned char CH2INTCTRL; unsigned char CH3INTCTRL; unsigned char INTFLAGS; WORDREGISTER(CMP); unsigned char PRESCALER; unsigned char reserved_0x1a; unsigned char reserved_0x1b; unsigned char CALCTRL; DWORDREGISTER(CAL); } ADC_t; // Channel 0 MUX Control // Channel 1 MUX Control // Channel 2 MUX Control // Channel 3 MUX Control // Control Register A // Control Register B // Reference Control // Event Control // Channel 0 Result // Channel 1 Result // Channel 2 Result // Channel 3 Result // Channel 0 Interrupt Control // Channel 1 Interrupt Control // Channel 2 Interrupt Control // Channel 3 Interrupt Control // Interrupt Flags // Compare Value // Clock Prescaler // Calibration Control // Calibration Value In Code Listing 3-4, the ADC channel result registers CH0RES, CH1RES, CH2RES, CH3RES and the compare register, CMP, are 16-bit values. These are declared using the WORDREGISTER macro shown in Code Listing 3-5. The calibration register, CAL, is a 32-bit value, declared using the DWORDREGISTER shown in Code Listing 3-6. 7

Code Listing 3-5. WORDREGISTER Macro. #define WORDREGISTER(regname) \ union { \ unsigned short regname; \ struct { \ unsigned char regname ## L; \ unsigned char regname ## H; \ }; \ } Code Listing 3-6. DWORDREGISTER Macro. #define DWORDREGISTER(regname) \ union { \ unsigned long regname; \ struct { \ unsigned char regname ## 0; \ unsigned char regname ## 1; \ unsigned char regname ## 2; \ unsigned char regname ## 3; \ }; \ } As seen, the WORDREGISTER macro uses H and L suffix for the high and low bytes respectively. The DWORDREGISTER uses number suffix to indicate the byte order. Both the 16-bit and 32-bit registers can be accessed in 16-bit/32-bit mode, by using the register name without suffix as shown in Code Listing 3-7. Code Listing 3-7. Accessing registers of varying size. unsigned char tempbyte; unsigned int tempword; unsigned long tempdword; tempbyte = ADCA0.CTRLA; // Read control register A tempword = ADCA0.CH0RES; // Read Channel 0 16-bit result tempdword = ADCA0.CAL; // Read 32-bit Calibration value Code Listing 3-7 shows how the single byte register CTRLA is read, how the two CH0RES[H:L] registers are read using a 16-bit operation, and how the four CAL[3:0] registers are read in a 32-bit operation. C compilers handle multi-byte registers automatically. Note however that in some cases it may be required to read and write 8 AVR1000

AVR1000 multi-byte registers in one atomic operation to avoid corruption. In this case, interrupts must be disabled during the multi-byte access to make sure that an interrupt service routine does not interfere with the multi-byte access. AVR1306 includes examples on how atomic access of registers is done for the XMEGA Timer/Counter modules. 3.3 Module Addresses Definitions of all peripheral modules are found in the device header files available for the XMEGA. The address for the modules is specified in ANSI C to make it compatible with most available C compilers. Code Listing 3-8 shows how ADC 0 on port A is defined. Code Listing 3-8. Peripheral module definition. #define ADCA (*(volatile ADC_t *) 0x0200) 3.4 Bit Masks and Bit Group Masks 3.4.1 Bit Mask Code Listing 3-8 shows how the module instance definition uses a dereferenced pointer to the absolute address in the memory, coinciding with the module instance base address. The module pointers are pre-defined in the XMEGA header files, it is therefore not necessary to add these definitions in the source code Register bits can be manipulated using pre-defined masks, or alternatively bit positions. Bit positions are not recommended for most tasks. The pre-defined bit masks are either related to individual bits, called a bit mask or a bit group, called a bit group mask, or group mask for short. A bit mask is used both when setting and clearing individual bits. A bit group mask is mainly used when clearing multiple bits in a bit group. Setting multiple bit that are part of a bit group is covered in section 3.5. Consider a Timer Counter Control Register D, CTRLD. The bit groups, bit names, bit positions and bit masks of this register can be seen in Table 3-1. Table 3-1. Bit groups, bit names, bit positions and bit masks for bits in Timer Counter Control register D CTRLD. Bit Group EVACT - EVSEL Bit name EVACT2 EVACT1 EVACT0 EVDLY EVSEL3 EVSEL2 EVSEL1 EVSEL0 Bit position 7 6 5 4 3 2 1 0 Bit mask 0x80 0x40 0x20 0x10 0x08 0x04 0x02 0x01 Since the names of bits need to be unique for the compiler to handle them, all bits are prefixed with the module type it belongs to. In many cases, the module type name is abbreviated. For all bit defines related to the Timer/Counter modules, the bit names are prefixed by TC_. To differentiate between bit masks and bit positions, a suffix is also appended. For a bit mask, the suffix is _bm. The name of the bit mask for the EVDLY bit is thus TC_EVDLY_bm. Code Listing 3-9 shows the typical usage of a bit mask. The EVDLY bit 9

in the CTRLD register of Timer/Counter D0 is set, leaving all the other bits in the register unchanged. Code Listing 3-9. Bit mask usage. TCD0.CTRLD = TC_EVDLY_bm; // With bit mask specifier. 3.4.2 Bit Group Masks Many functions are controlled by a group of bits. Timer Counter CTRLD register the EVACT[2:0] and the EVSEL[3:0] bits are grouped bits. The value of the bits in a group selects a specific configuration. When changing bits in a bit group it is often required to clear the bit group before assigning a new value. To put it in another way: It is not enough to set the bits that should be set, it is also required to clear the bits that should be cleared. To make this easy a bit group mask is defined. The group mask uses same name as the bits in the bit group and is suffixed _gm. Code Listing 3-10 shows how the group mask relates to the bit masks. In reality, the group mask values are pre-calculated in the header files, so the compiler does not need to calculate the same constant over and over again. Code Listing 3-10. Group mask and bit mask relation. #define TC_EVACT_gm (TC_EVACT2_bm TC_EVACT1_bm TC_EVACT0_bm) The bit group mask is primarily intended to clear the old configuration of a bit group before writing a new value. Code Listing 3-11 shows how this can be done. The code will clear the EVACT bit group in the CTRLD register of Timer/Counter D0. This construct is not very useful in itself. The group mask will typically be used in conjunction with a group configuration mask, which is covered in section 3.5. Code Listing 3-11. Group mask usage. TCD0.CTRLD &= ~(TC_EVACT_gm); // Clear group bits with group mask. 3.5 Bit group Configuration Masks It is often required to consult the datasheet to investigate what bit pattern needs to be used when setting a bit group to a desired configuration. This also applies when reading or debugging code. To increase the readability and to minimize the likeliness of setting bits in bit groups incorrectly, a number of group configuration masks are made available. Each group configuration mask selects a configuration for a specific group mask. The name of a group configuration mask is a concatenation of the module type, the bit group name, a description of the configuration and a suffix, _gc, indicating that this is a group configuration. See Figure 3-2 for an example. 10 AVR1000

AVR1000 Figure 3-2. Group configuration name composition (using USART receive complete interrupt level bits as example). USART_RXCINTLVL_HI_gc Module prefix Bit group name Configuration name "Group configuration" suffix Inspecting the group configuration Figure 3-2, one can see that it is used to select a configuration for the RXCINTLVL bits in a USART module. This specific group configuration selects a high (HI) interrupt level. The bit group for the Receive Complete Interrupt Level consists of two bits, RXINTLVL[1:0]. Table 3-2 shows the available group configurations for this bit group. The configuration names are OFF, LO, MED and HI. These names make it very easy to write and maintain code, as it requires very little effort to understand what configuration the specific configuration mask selects. Table 3-2. RXINTLVL bits and corresponding interrupt level of module interrupt. RXINTLVL1 RXINTLVL0 Interrupt level Group configuration mask 0 0 Interrupt off USART_RXCINTLVL_OFF_gc 0 1 Low interrupt level USART_RXCINTLVL_LO_gc 1 0 Medium interrupt level USART_RXCINTLVL_MED_gc 1 1 High interrupt level USART_RXCINTLVL_HIGH_gc Code Listing 3-12. Changing a bit group configuration. To change a bit group to a new configuration, the bit group configuration is typically used in conjunction with the bit group mask, to ensure that the old configuration is erased first. Code Listing 3-12 shows how the group mask and a configuration mask can be used to reconfigure the USART C0 Receive Complete Interrupt level to medium level. USARTC0.INTCTRL = (USARTC0.INTCTRL & ~USART_RXCINTLVL_gm ) USART_RXCINTLVL_MED_gc; Note that though it may be tempting to split the code in Code Listing 3-12 into two separate code lines, one that clear the bit group and one that sets the new value, this is not recommended. Since the INTCTRL register is defined as volatile, two separate code lines will trigger reading and writing the INTCTRL register twice instead of once. In addition to making the code inefficient, this can put the peripheral in an unintended state. The use of group masks to clear bits is not always required. Code Listing 3-13 shows how all interrupt levels of USARTC0 can be configured at the same time. Receive Complete, Transmit Complete and USART Data Register Empty interrupt levels are set to MEDIUM, OFF and LOW interrupt levels respectively. 11

Code Listing 3-13. Setting all configurations in a register at the same time. USARTC0.INTCTRL = USART_RXCINTLVL_MED_gc USART_TXCINTLVL_OFF_gc USART_DREINTLVL_LO_gc; 3.5.1 Enumeration of Group Configuration masks Unlike bit masks and group masks, the bit group configuration masks are defined using C enumerators. One enumerator is defined for each bit group. The enumerator for the USART RXCINTLVL bit group is shown in Code Listing 3-14. Code Listing 3-14. USART RXCINTLVL enumerator typedef enum { USART_RXCINTLVL_OFF_gc = (0x00 << 4); USART_RXCINTLVL_LO_gc = (0x01 << 4); USART_RXCINTLVL_MED_gc = (0x02 << 4); USART_RXCINTLVL_HI_gc = (0x03 << 4); } USART_RXCINTLVL_t; 3.6 Functions Calls and Module Drivers As seen in Code Listing 3-14, the name of the enumerator is a concatenation of the module type (USART), the bit group (RXCINTLVL) and a suffix (_t) that indicates that this is a data type. Each of the enumerator constants behaves much like a normal constant when used on its own. However, using an enumerator has the advantage that it creates a new data type. USART_RXCINTLVL_t can be used as a type name, just like an int or char. An enumerator constant can be used directly as integer, but assigning an integer to an enumerator type will trigger a compiler warning. This can be used to the programmers advantage. Imagine a function that sets the receive complete interrupt level for a USART module. If the function accepts the interrupt level as an integer type (e.g. unsigned char), any legal or illegal value can be passed to the function. If the function instead accepts a parameter of type USART_RXCINTLVL_t, only the four pre-defined constants in the USART_RXCINTLVL_t enumerator can be passed to the function. Passing anything else will result in a compiler warning. Notice that the constants in Code Listing 3-14 are shifted to the actual bit position. This means that the enumerator contstants are the actual values that shall be written to the register. No additional shifting is needed. When writing drivers for module types that have multiple instances, the fact that all instances have the same register memory map, can be utilized to make the driver reusable for all instances of the module type. If the driver takes a pointer argument, pointing to the relevant module instance, the driver can be used for all modules of this type. When considering portability this represents a great advantage. 12 AVR1000

AVR1000 Consider a device with 8 Timers/Counters. The functions to initialize and access the Timer/Counter modules can be shared by all module instances. Even though there is a small overhead in passing the module pointer to the functions, the total code size will often be reduced because the code is reused for all instances of each module type. Even more important, development time, maintenance cost, and portability can be greatly improved by using this approach. Code Listing 3-15 shows a function that uses a module-pointer to select a clock source for any Timer/Counter module. Code Listing 3-15. Example function using module instance pointer void TC_ConfigClockSource(volatile TC_t * tc, TC_CLKSEL_t clockselection) { tc->ctrla = tc->ctrla & ~TC_CLKSEL_gm clockselection; } The function takes two arguments: a module pointer of the type, TC_t, and a group configuration type, TC_CLKSEL_t. The code in the function uses the Timer Counter module pointer to access the CTRLA register to set a new clock selection for the Timer/Counter module provided through the tc parameter. Code Listing 3-16 shows how the function in Code Listing 3-15 can be used to configure different Timer/Counter modules with different clock selections. Code Listing 3-16. Calling a function that takes a module pointer as parameter TC_ConfigClockSource (&TCC0, TC_CLKSEL_OFF_gc); TC_ConfigClockSource (&TCC1, TC_CLKSEL_DIV1_gc); TC_ConfigClockSource (&TCD0, TC_CLKSEL_DIV2_gc); TC_ConfigClockSource (&TCD1, TC_CLKSEL_DIV1024_gc); 4 Alternative Ways of Writing Code 4.1 Register Names For convenience and to avoid forcing AVR programming veterans to change their programming style it is still possible to use a programming style that does not involve structs. It is also possible to use the bit name style that is used for megaavr. This section briefly describes alternative ways of accessing registers and using bit names. It is possible to access any register without using the module structs. To refer to a register directly, concatenate the module instance name, an underscore and the register name. The same naming convention is used when programming in assembly. Example: To access the CTRLA register of Timer/Counter C0, use the name TCC0_CTRLA. 13

4.2 Bit Positions It is possible to use bit masks to set or clear bits. A bits position within a register is defined using the same name as the bit mask, with an additional prefix, _bp for bit position. Code Listing 4-1 shows how the bit position can be used to configure a register. Code Listing 4-1. Alternative register access code. PORTB_OUT = (1 << PORTB_OUT0_bp); // Set PORTB_OUT, bit0. The bit position definitions are included for compatibility reasons. They are also needed when programming in assembly for instructions that use a bit number. 5 Summary For reference, an overview of the different postfixes used when dealing with bit configuration is listed in Table 5-1. Table 5-1. Overview of postfixes Postfix Meaning Example _gm Group Mask TC_CLKSEL_gm _gc Group Configuration TC_CLKSEL_DIV1_gc _bm Bit Mask TC_CCAEN_bm _bp Bit Position TC_CCAEN_bp Using the suggested methods to write C-code for XMEGA is by no means mandatory, but the advantages offered should be considered used to ensure robust, portable, reusable, and highly readable code. The larger the project, and the more features the device has the bigger the advantage. For small projects it can be argued that there is no benefit, but turning that argument upside down one can say that there is not disadvantage either. One thing is for sure: good code style is always an advantage. 14 AVR1000

Disclaimer Headquarters International Atmel Corporation 2325 Orchard Parkway San Jose, CA 95131 USA Tel: 1(408) 441-0311 Fax: 1(408) 487-2600 Atmel Asia Room 1219 Chinachem Golden Plaza 77 Mody Road Tsimshatsui East Kowloon Hong Kong Tel: (852) 2721-9778 Fax: (852) 2722-1369 Atmel Europe Le Krebs 8, Rue Jean-Pierre Timbaud BP 309 78054 Saint-Quentin-en- Yvelines Cedex France Tel: (33) 1-30-60-70-00 Fax: (33) 1-30-60-71-11 Atmel Japan 9F, Tonetsu Shinkawa Bldg. 1-24-8 Shinkawa Chuo-ku, Tokyo 104-0033 Japan Tel: (81) 3-3523-3551 Fax: (81) 3-3523-7581 Product Contact Web Site www.atmel.com Technical Support avr@atmel.com Sales Contact www.atmel.com/contacts Literature Request www.atmel.com/literature Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN ATMEL S TERMS AND CONDITIONS OF SALE LOCATED ON ATMEL S WEB SITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel s products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life. 2008 Atmel Corporation. All rights reserved. Atmel, logo and combinations thereof, AVR, AVR Studio and others, are the registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others.