The AVR LibC library provides a subset of the standard C library, for use while developing programs for Atmel AVR microcontrollers. This tutorial provides details on using the AVR LibC library in your projects.

TOC

• AVR LibC Setup
• AVR LibC Specific Programming Notes
  • Library Functions
  • ROM Strings
  • Function Register Access
  • Interrupt API

AVR LibC Setup

Before you can use the AVR LibC library, it needs to be installed along with a few other programs (the compiler and assembler for AVR targets). The installation of all requirements is described in detail on the Free software AVR development toolchain page.

AVR LibC Programming Notes

Library Functions

In addition to the AVR specific functions (stuff like watchdog timer setup), a number of the standard C library functions are supported by AVR LibC: string functions like strcpy, strlen, etc. math functions like sin, cos, sqrt and pow, I/O functions like printf and scanf and more. You must remember though that the entire standard library isn't available--certain functions have yet to be implemented (perhaps you can help?) while others may not be possible or even make sense on the platform. Check the AVR LibC docs before you code.

ROM Strings

If you are using many constant strings in your application, for instance while using an LCD display or speaking to a serial port through the UART, you'll want to save RAM by storing the constant strings (and leaving them) in the comparatively vast ROM. You can do this thanks to the AVR LibC Program Space String Utilities. By adding an

#include <avr/pgmspace.h>

to your C source file, you gain access to functions which allow access to data stored in the device's program space (the flash memory ROM). With the program space string utilities, you can declare and manipulate PGM_P variables: pointers to strings in program space. In addition to low level pgm_read_* functions, they provide a number of _P equivalent string manipulation functions, such as

• void * memcpy_P (void *, PGM_VOID_P, size_t)
• char * strcat_P (char *, PGM_P)
• int strcmp_P (const char *, PGM_P)
• char * strcpy_P (char *, PGM_P)
• size_t strlen_P (PGM_P)
• and more...

Function Register Access

Lots of the microcontroller programmer's work involves dealing with I/O and other function registers, often on a bit-by-bit basis. AVR-LibC provides two methods by which this may be accomplished. You may use specific IO instructions on IO address space, e.g.

outb(PORTB, 0xFF);

Or you can choose to use the symbolic address directly:

PORTB = 0xFF;

The former method may be preferable if you plan to compile the program using other AVR platform C compilers. The latter has the advantage of clarity. For instance, here are two equivalent instructions, taken from the AVR LibC documentation:

outb(DDRD, inb(DDRD) & ~LCDBITS);

DDRD &= ~LCDBITS;

Interrupt API

The vector table, described above, is set to point interrupt routines with predetermined names. The library provides default interrupt routines, which get used unless overridden.

If you wish to provide an interrupt routine for a particular signal you must, in addition to any required AVR setup, create the function using one of the SIGNAL() or INTERRUPT() macros, along with the appropriate signal names. There are a number of preset signal names, such as

• SIG_ADC (ADC conversion done)
• SIG_EEPROM_READY
• SIG_INTERRUPT0..7 (external interrupts 0 to 7)
• SIG_OVERFLOW0..3 (timer/counter overflow)
• SIG_UART0_DATA, SIG_UART0_RECV, SIG_UART0_TRANS (UART empty/receive/transmit interrupts)
• etc.

To create a interrupt routine, select a macro-signal combination and

#include <avr/signal.h>

INTERRUPT(SIG_OVERFLOW0)
{
    /* Your overflow handler routine */
}

For the same overflow signal, you could have written

#include <avr/signal.h>

SIGNAL(SIG_OVERFLOW0)
{
    /* Your overflow handler routine */
}

The difference between the two is the state of the global interrupts as your enter the function. In the case of INTERRUPT(), global interrupts are initally enabled whereas for SIGNAL() they are disabled (your routine can not be itself interrupted).

Things to remember when using interrupts:

• The list of signal names is constant but exactly which interrupts will be available to you depends on the specific AVR microcontroller flavor you select. Check the datasheet.
• Perform your peripheral setup before you enable interrupts. A number of steps may be required, depending on the specific peripheral. For instance, here is the setup for a 16 bit timer:

  #include <avr/io.h>
  #include <avr/interrupt.h>
  
  /* ... */
  
  
  /* enable the timer/counter1 overflow interrupt in the T/C int mask register */
  timer_enable_int(_BV(TOIE1));
  
  /* no compare/pwm/capture mode */
  TCCR1A = 0;
  
  /* setup this timer's prescaler */
  TCCR1B = TIMERSCALE;
  
  /* Setup the timer starting value */
  TCNT1L = MYTIMERSTARTLOW;
  TCNT1H = MYTIMERSTARTHIGH;
  		

  A number of constants and function registers are used, the MY... values are user defined while the others are set through the io.h header. The important thing here is to notice that it is often important to perform a good deal of initial setup before a peripheral and its interrupts may be used.

• When you are ready to receive interrupts, enable them by using:

  
  #include <avr/interrupt.h>
  
  /* ... */
  
  /* enable global interrupts */
  sei();