2 AVR1000b Getting Started with Writing C-Code for AVR® MCUs

Any documentation related to Microchip products can be found at:

• Microchip Data Sheets

The device data sheets, for the device families of interest in this document, can be found at:

• ATtiny416 Overview
• ATtiny212 Overview
• ATtiny3217 Overview
• ATtiny1634 Overview
• ATmega4809 Overview
• ATmega808 Overview
• AVR128DA28 Overview

The pin description can be found in any device data sheet. The pinout is contained in the Pinout, Pin Configurations section, or any other name convention, depending on the device. The pinout of the ATmega809/1609/3209/4809 48-pin devices is presented in Figure 2-2.

The configurable functionalities for each I/O pin are described in the I/O Multiplexing and Considerations section, or the Alternate Port Functions subsection of the I/O Ports section, depending on the device. If an evaluation board is used, such as AVR128DA48 Curiosity Nano, the user needs to know how the microcontroller’s pins are allocated on the specific board. The information is available on the AVR128DA48 Curiosity Nano webpage, in the AVR128DA48 Curiosity Nano Schematics document. Other documents that describe the AVR128DA48 Curiosity Nano board and microcontroller characteristics are available on the same webpage.

An AVR microcontroller is comprised of several building blocks: AVR CPU, SRAM, Flash, EEPROM and several peripheral modules called module types. Throughout this document, all peripheral modules will be referred to as modules.

Newer AVR microcontroller families can have one or more instances of a given module type. All instances have the same features and functions. Some module types are a subset of others and inherit some of their features. The inherited features are fully compatible with the respective module type. For example, the subset module for a timer can have fewer compare and capture channels than a full timer module.

A module type can be the Universal Synchronous-Asynchronous Receiver Transmitter (USART), while the module instance is, e.g., USART0, where the 0 suffix indicates the instance is “USART number 0”. 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 fixed base address in the I/O 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 I/O 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. The peripheral module address map can be found in the data sheet and shows the base address for each peripheral.

Each module has several 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.

Table 2-1 presents the base address of some of the ATtiny804/1604 peripherals.

Every module has a dedicated section presenting the features that the module has, a functional description of the module, and the specific signals and guidelines on how to configure a certain mode of operation with all the terminology explained. At the end of a module section, there is a register description subsection that contains the scope of every register, the initial value, and if it is readable or writable. It also provides the position of every configurable/accessible bit of a register.

All the registers, their addresses offsets, and the bit names and positions are described in the Register Summary section for each module. The register summary for the ADC module is presented in Figure 2-4.

This section describes the register and bit naming conventions that can be found in the device data sheet and in the header file used to develop any application.

CCP registers are used to protect system-critical I/O register settings from accidental modification, as well as Flash self-programming from accidental execution. Writing to a register under CCP is possible only after writing a specific signature/key to the CCP register, which is part of the CPU module. The values of the signatures can be found in the Configuration Change Protection subsection of the device data sheet.

There are two types of writes to a protected register, each with its key:

• protected I/O registers (the key/signature is IOREG)
• protected self-programming (the key/signature is SPM)

Some of the registers that are under the Configuration Change Protection are listed in the table below.

Changes to the protected I/O registers or bits, or execution of protected instructions are only possible after the CPU writes one of these signatures to the CCP register. The signatures are listed in the description of the CCP (CPU.CCP) register.

A code example is provided in 2.3.5 Writing to Configuration Change Protection (CCP) Registers.

The fuses hold the device configuration and are part of the nonvolatile memory. They are available from device power-up. Their values are maintained through a chip erase. The fuses can be read by the CPU or the programming interface (e.g., UPDI), but can only be programmed or cleared through the program/debug interface. The configuration values stored in the fuses are copied to their respective target registers at the end of the start-up sequence so that the fuse values can be used by the CPU.

The Fuse Summary table can be found in the Memories → Fuses (FUSE) subsection from the device data sheet. An example extracted from the ATmega4808/4809 data sheet is presented below.

A code example is provided in 2.3.6 Configuring Fuses.

All registers for a given peripheral module are placed in one continuous memory block. Registers that belong to different modules are not mixed up, which makes it possible to organize all peripheral modules in C structures, where the instance macro is defined as shown in the code below. The definitions of all peripheral modules are found in the device header files available for these AVR devices. The address for the modules is specified in ANSI C to make it compatible with most available C compilers.

#define PORTMUX           (*(PORTMUX_t *) 0x0200) /* Port Multiplexer */
#define PORTA                (*(PORT_t *) 0x0400) /* I/O Ports */
#define PORTB                (*(PORT_t *) 0x0420) /* I/O Ports */
#define PORTC                (*(PORT_t *) 0x0440) /* I/O Ports */

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 defined in the header files; therefore, it is not necessary to add these definitions in the source code.

For example, the base address of the PORTA module is 0x0400. The module with all its registers and reserved bytes has an available memory space from 0x0400 to 0x0420, which means 32 bytes in decimal. Therefore, the PORT_t contains 32 allocated bytes for all its registers (or reserved bytes).

The user can access any register using the structure configuration of the modules. The ADC can be fully configured using the steps found in the data sheet, in the module’s description specific section. For example, the recommended steps to initialize the ADC are presented in ADC - Analog-to-Digital Converter → Functional Description → Initialization. Register bits can be manipulated using bit masks or bit position masks, which are defined in the header file. The predefined masks are either related to individual bits, in which case they are called bit masks, or to a group of bits (bit field), in which case they are called a bit group mask, or a group mask. For example, the ADC0 module can be enabled and configured to start a conversion cycle by using bit masks.

Setting and clearing register bits are fundamental operations used in embedded programming and represent a technique any application is based on.

The Read-Modify-Write operations are a class of atomic operations. They read a memory location and simultaneously write a new value to it, either with a completely new value or a part of the previous value.

As it has wide applicability, reading the value of a bit is mainly used in conditional expressions (e.g., if statement) and as a condition in loop expressions (e.g., while statement). A common use case of this technique is polling on an interrupt flag, which means reading the value of the bit and executing a set of instructions if the bit is set/clear.

To initialize a register, the user must find the desired configuration by consulting the device data sheet. Then, the register bits must be set or cleared so that the value in the register matches the desired configuration.

Register initialization is most often performed as part of device initialization after Reset when the register is in a known Reset state (default).

The Reset value for all bits and bit fields is ‘0’ for most AVR registers. Figure 2-13 shows how to find the Reset value and all the register’s bits configurations desired for this example.

Read-Modify-Write operations are not needed when working with bit masks or -positions if the Reset value of the register is 0x00, and the register can be configured in a single line.

The desired configuration can be, for example:

• ADC is enabled – the ENABLE bit will be ‘1’
• ADC is operating in Differential mode – the CONVMODE bit will be ‘1’
• ADC will run with 10-bit resolution – the RESSEL bit field value will be 0x00 (default)

This configuration can be implemented by using either the binary, hexadecimal, or decimal value (as presented below) and writing the resulting value directly to the register.

ADC0.CTRLA = 0b00100001;   /* binary */
ADC0.CTRLA = 0x21;         /* hexadecimal */
ADC0.CTRLA = 33;           /* decimal */

However, to improve the code readability (and potentially the portability), it is recommended to use the device defines shown in the upcoming sections.

The USART0 Control C register has a Reset value of 0x03. In this case, there is a need for a Read-Modify-Write operation to initialize one of the other bits or bit fields without changing the value of the CHSIZE bit field. Figure 2-14 shows this register.

This section covers considerations when updating a register bit field, using various header file defines. The RXMODE bit field will be used as an example, where an update is made compared to the initialization presented below.

USART0.CTRLB = USART_RXEN_bm            /* Receiver Enable */
             | USART_TXEN_bm            /* Transmitter Enable */
             | USART_RXMODE_LINAUTO_gc; /* LIN Constrained Auto-Baud mode */

The following subsections will provide code examples to change the Receiver Mode (RXMODE) configuration to Generic Auto-Baud (GENAUTO) mode. The available configurations for this bit field, as they are in the device data sheet, are presented in the table below.

The advantages of using the recommended coding style are:

• Obtaining a more readable code. By using the group configuration mask, the user will know for sure what configuration is being set – the configuration name being contained in the mask name.
• Obtaining a more compact code. The group mask will help the user clear all the bits in a bit field, without the need of using a bit mask for each bit. The configuration mask can also be used to configure the entire bit field.
• The code is easier to maintain. For example, to change a bit field configuration, the user will only have to change the group configuration mask name instead of changing each bit value using bit masks or bit positions.

Attempting to write to a protected register without following the appropriate CCP unlock sequence leaves the protected register unchanged. The sequence, specified in the device data sheet, typically involves writing a signature to the CPU.CCP register and then, within four instructions, writing the desired value to the protected register.

The CCP signatures are provided by the device header file, as presented below.

/* CCP signature select */
typedef enum CCP_enum
{
    CCP_SPM_gc = (0x9D<<0),    /* SPM instruction protection */
    CCP_IOREG_gc = (0xD8<<0),  /* I/O register protection */
} CCP_t;

The following example shows how to write to a register under CCP using an IOREG signature. The main clock prescaler division will be set to 16.

CCP = CCP_IOREG_gc; /* Write the needed signature to CCP*/
CLKCTRL.MCLKCTRLB = CLKCTRL_PDIV_16X_gc; /* Set the prescaler division to 16 */

The following example shows how to write to a register under CCP using the SPM signature.

CPU.CCP = CCP_SPM_gc; /* Write the needed signature to CCP*/
NVMCTRL.CTRLA = NVMCTRL_CMD_FLPER_gc; /* Flash Page Erase Enable*/

Thus, the recommended way of writing to a protected I/O register is by using the ccp_write_io function. To use this function, the following header file must be included.

#include <avr/cpufunc.h> /* Required header file */

The following code example provides the same functionality as the example presented above, but using the ccp_write_io function.

/* Set the prescaler division to 16 */
ccp_write_io((void *) & (CLKCTRL.MCLKCTRLB), (CLKCTRL_PDIV_16X_gc)); 

Alternatively, a macro is defined to write a value to a CCP register. This is protected through the XMEGA® CCP mechanism, which implements the timed sequence that is required for CCP.

#include <avr/xmega.h> /* Required header file */

These macros must be used to write to the desired registers, as presented in the code examples below.

/* Select the 32 kHz internal Ultra-Low Power oscillator */
_PROTECTED_WRITE(CLKCTRL.MCLKCTRLA, CLKCTRL.MCLKCTRLA | CLKCTRL_CLKSEL_OSCULP32K_gc);
/* Write page command */
_PROTECTED_WRITE_SPM(NVMCTRL.CTRLA, NVMCTRL_CMD_PAGEWRITE_gc);

The fuses are preprogrammed but the fuse registers can be altered by the user. A fuse can be changed only by programming it. However, some fuse values are loaded into registers and these register values can be changed during run-time. The fuses can be configured by writing C-code, as described in the following subsections.

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. This represents a great advantage when considering portability. Moreover, the written code may be portable between devices of the same family. Details on the compatibility between devices from the same family are provided in the data sheet’s series Overview section, and some differences are shown in Figure 2-18.

In a device with multiple timers/counters, the functions to initialize and access these modules can be shared by all module instances, instead of replicating the same lines of code for every instance. Even though there is a small overhead in passing the module pointer to the functions, the total code size will be reduced because the code is reused for all instances of each module type. Moreover, development time, maintenance cost, and portability can be greatly improved by using this approach.

The code below shows a function that uses a module pointer to select a clock source for any timer/counter module.

void TC_ConfigClockSource (volatile TCB_t *tc, TCB_CLKSEL_t clockSelection)
{
	tc->CTRLA = (tc->CTRLA & ~TCB_CLKSEL_gm) | clockSelection;
}

The function takes two arguments: A module pointer of type TCB_t and a group configuration type TCB_CLKSEL_t. The code in the function uses the timer/counter module pointer to access the CTRLA register and set a new clock selection for the timer/counter module with the address provided through the tc parameter. The code below shows how the function described above is used to set different configurations for different timer/counter instances.

/* Configure the TCB0 clock selection as CLKDIV2*/
TCB_ConfigClockSource (&TCB0, TCB_CLKSEL_CLKDIV2_gc); 
/* Configure the TCB0 clock selection as CLKDIV1*/
TCB_ConfigClockSource (&TCB0, TCB_CLKSEL_CLKDIV1_gc); 
/* Configure the TCB1 clock selection as CLKDIV2*/
TCB_ConfigClockSource (&TCB1, TCB_CLKSEL_CLKDIV2_gc); 
/* Configure the TCB2 clock selection as CLKDIV2*/
TCB_ConfigClockSource (&TCB2, TCB_CLKSEL_CLKDIV2_gc);  

It is possible to access any register without using the module structures. To refer to a register directly, concatenate the module instance name, then add an underscore and the register name. The same naming convention is used when programming in assembly.

For example, to access the CTRLA register of Timer/Counter type B, instance 0, the name TCB0_CTRLA can be used, instead of the access through the structures.

It is possible to use bit masks to set or clear bits. A bit’s position within a register is defined using the same name as the bit mask, but a different suffix. The code below shows how the bit position can be used to configure a register.

PORTB_OUT |= (1 << PIN0_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.

Virtual port (VPORT) registers allow some PORT registers to be mapped virtually in the bit accessible I/O memory space. When this is done, writing to the VPORT register will be the same as writing to the real PORT register. This enables the use of I/O memory specific instructions, such as bit manipulation instructions (SBI/CBI), on a PORT register that resides in the extended I/O memory space. The number of available virtual ports is, in most cases, limited to four or six, resulting in a smaller number of available virtual ports than the number of PORT modules. The advantages of using virtual ports are a smaller and less complex program and less Flash memory used.

A compatibility diagram is presented in Figure 2-19, which explains what coding styles are available for specific AVR product families.

This subsection contains an example on how to configure a PORT to turn on an LED when pressing a user button. To identify which pins of the microcontroller are routed to the user LED and to the user button, the used board schematic is necessary. For the AVR128DA48 Curiosity Nano board used for this example, the LED is connected to the sixth pin of PORTC, PC6, and the button is connected to the seventh pin of PORTC, PC7. To make sure this is the correct configuration of the pins, the user must check the board schematic.

The code below shows how to write code for turning on and off an LED, using bit position macros.

/* Direction configuration of the pins */ 
/* Read-Modify-Write: Software */
PORTC.DIR |= (1 << PIN6_bp);               /* Output for the user LED */
PORTC.DIR &= ~(1 << PIN7_bp);              /* Input for the user button */
PORTC.PIN7CTRL |= (1 << PORT_PULLUPEN_bp); /* The pull-up configuration */
while (1)
{
    if(PORTC.IN & (1 << PIN7_bp))          /* Check the button state */
    {
        /* The button is released */
        PORTC.OUT |= (1 << PIN6_bp);       /* Turn off the LED */
    }
    else
    {
        /* The button is pressed */
        PORTC.OUT &= ~(1 << PIN6_bp);      /* Turn on the LED */
    }
}

The code below provides the same functionality but using the bit masks.

/* Direction configuration of the pins */
/* Read-Modify-Write: Software */
PORTC.DIR |= PIN6_bm;               /* Output for the user LED */
PORTC.DIR &= ~ PIN7_bm;             /* Input for the user button */
PORTC.PIN7CTRL |= PORT_PULLUPEN_bm; /* The pull-up configuration */
while (1)
{
    if(PORTC.IN & PIN7_bm)          /* Check the button state */
    {
        * The button is released */
        PORTC.OUT |= PIN6_bm;       /* Turn off the LED */
    }
    else
    {
        /* The button is pressed */
        PORTC.OUT &= ~(PIN6_bm);    /* Turn on the LED */
    }
}

Also, the SET and CLR registers can be used to set and clear the pin value without Read-Modify-Write operations, as shown in the code below. This allows performing the setting and the clearing of the desired value using an atomic instruction, instead of reading the register value first. The main advantage is that this action cannot be interrupted. Only one instruction is executed instead of three (Read-Modify-Write).

PORTC.DIRSET = PIN6_bm;             /* Output for the user LED */
PORTC.DIRCLR = PIN7_bm;             /* Input for the user button */
PORTC.PIN7CTRL |= PORT_PULLUPEN_bm; /* The pull-up configuration */
    
while (1)
{
    /* Read-Modify-Write: Hardware */
    if(PORTC.IN & PIN7_bm)          /* Check the button state */
    {
        /* The button is released */
        PORTC.OUTSET = PIN6_bm;     /* Turn off the LED */
    }
    else
    {
        /* The button is pressed */
        PORTC.OUTCLR = PIN6_bm;     /* Turn on the LED */
    }
}

Another way to configure the direction and set/clear the value of the output pin is by using virtual ports, as presented in the code below.

/* Direction configuration of the pins */
/* Read-Modify-Write: VPORT registers */
VPORTC.DIR |= PIN6_bm;              /* Output for the user LED */
VPORTC.DIR &= ~PIN7_bm;             /* Input for the user button */
PORTC.PIN7CTRL |= PORT_PULLUPEN_bm; /* The pull-up configuration */
while (1)
{
    if(VPORTC.IN & PIN7_bm)         /* Check the button state */
    {
        /* The button is released */
        VPORTC.OUT |= PIN6_bm;      /* Turn off the LED */
    }
    else
    {
        /* The button is pressed */
        VPORTC.OUT &= ~PIN6_bm;     /* Turn on the LED */
    }
}

This section presents a simple configuration example for the ADC0 module on an AVR128DA48 device from the AVR DA series of devices. The information needed to program this controller can be found in the device data sheet, as mentioned in Section 1: Data Sheet Structure and Naming Conventions.

To fully configure the ADC, the user can follow the recommended initialization steps that can be found in the Functional Description subsection from the ADC – Analog-to-Digital Converter section of the data sheet.

After the ADC prescaler is configured, the ADC module is enabled, and a conversion is started. In the code below, the configurations are made using the bit position macros.

	/* ADC register configuration using bit position macros */
	ADC0.CTRLC |= (1 << ADC_PRESC0_bp) | (1 << ADC_PRESC1_bp); /* Configuring the prescaler bits. Configuration: DIV8 */
	ADC0.CTRLA |= (1<< ADC_ENABLE_bp);         /* Enabling the ADC */
	ADC0.COMMAND |= (1<< ADC_STCONV_bp);       /* Starting a conversion */

Alternatively, the ADC can be configured using the bit masks, as in the code below.

	/* ADC register configuration using bit masks macros */
	ADC0.CTRLC |= ADC_PRESC0_bm | ADC_PRESC1_bm;               /* Configuring the prescaler bits. Configuration: DIV8 */
	ADC0.CTRLA |= ADC_ENABLE_bm;               /* Enabling the ADC */
	ADC0.COMMAND = ADC_STCONV_bm;              /* Starting a conversion */

To change the prescaler configuration, a group configuration mask can be used. The original configuration must be cleared first, as shown in the code below.

	/* Changing an ADC prescaler configuration, ensuring to clear the original configuration */
	ADC0.CTRLC = (ADC0.CTRLC & ~ADC_PRESC_gm) | ADC_PRESC_DIV4_gc;

This series of technical briefs utilizes the same principles recommended in this document, covering all peripherals for the megaAVR® 0-series family of AVR microcontrollers. Each technical brief starts with a summary of the use cases covered. Each use case is then developed, showing how to use the data sheet to configure the peripheral in the required configuration.

For example, the Getting Started with ADC technical brief provides an overview of the peripheral and a description on how to use the peripheral in several use cases in different operation modes: single conversion, free-running, sample accumulator, etc.

• TB3209 - Getting Started with ADC
• TB3211 - Getting Started with AC
• TB3213 - Getting Started with RTC
• TB3214 - Getting Started with TCB
• TB3215 - Getting Started with SPI
• TB3216 - Getting Started with USART
• TB3217 - Getting Started with TCA
• TB3218 - Getting Started with CCL
• TB3229 - Getting Started with GPIO

The following videos are particularly relevant for this technical brief.

• Getting Started with Atmel Studio 7 - Episode 10 - I/O View & Bare Metal Programming References
• Getting Started - AVR® in MPLAB® X - Context Data Sheet Help & AVR Interrupts

The following is a 28-part video series, which builds up functionality using the data sheet and device header files as primary programming references.

• Getting Started with AVR®

The XC compilers are comprehensive solutions for the software development of any suitable project. The MPLAB XC8 compiler supports all 8-bit PIC® and AVR microcontrollers⁽²⁾, and it is available as free, unrestricted-use download. A pro license is also available. By using a pro license, the user will obtain a more efficient code. Additionally, a certified XC8 Functional Safety license is now available.

When combined with the MPLAB X IDE, the front-end provides editing errors and breakpoints, that match corresponding lines in the source code, and single-stepping through C source code to inspect variables and structures at critical points.

More information on Microchip’s MPLAB X IDE can be found on the user guides page, by searching for “MPLAB X IDE User’s Guide”.

To program AVR microcontrollers, either the MPLAB X, Atmel Studio, or IAR Embedded Workbench IDEs can be used.

MPLAB X Integrated Development Environment (IDE) is an expandable and highly configurable software program. It incorporates powerful tools to help the user discover, configure, develop, debug and qualify embedded designs for most of Microchip’s microcontrollers and digital signal controllers. MPLAB X IDE offers support for AVR MCUs.

All the information needed to be familiar with Atmel Studio, including hands-on and video tutorials, is provided in this user’s guide: Getting Started with Atmel Studio 7. Additionally, information on all the project configurations needed to develop a project (fuse programming, oscillator calibration, interface setting, etc) can be found in the Atmel Studio 7 user’s guide. To find and develop more examples for any board, configure drivers, find example projects, and easily configure system clock settings, the online code configuration tool Atmel START can be used. For more details, refer to the Atmel START User Guide.

The IAR Embedded Workbench for AVR with all the features is described in the AN3419 - Getting Started with IAR Embedded Workbench for AVR application note.

The microcontroller families tinyAVR® 0/1-series, megaAVR 0-series, and AVR DA have also a series of Getting Started with dedicated guides available online, with information on how to create a project and what starter kit to use. Examples of these guides are listed below:

• Getting Started with megaAVR® 0-series
• Getting Started with tinyAVR® 1-series Microcontrollers
• Getting Started with tinyAVR® 0-series
• Getting Started with the AVR DA Family