Preprocessor directives

Preprocessor directives and macros in C for AVR microcontrollers are essential for optimizing code, improving readability, and making embedded systems more efficient.

These directives are processed before compilation, making them powerful tools for defining constants, creating reusable code snippets, and conditional compilation.

This tutorial will cover:

1. What preprocessor directives are
2. Types of preprocessor directives
3. Using #define macros effectively
4. Using #include for modular code
5. Conditional compilation with #ifdef and #ifndef
6. Compiler-specific directives like #pragma
7. Using #error for debugging
8. Best practices for preprocessor usage in embedded C

What Are Preprocessor Directives?

Preprocessor directives are special instructions that begin with # and are executed before the compilation process starts. These directives are not actual C code but commands for the compiler.

Common Uses:

• Defining constants without consuming memory
• Creating macros to simplify repetitive code
• Including files for modular programming
• Conditional compilation to include or exclude code blocks

Types of Preprocessor Directives

Using #define for Constants

The #define directive allows you to create named constants without using extra memory.

Example: Defining Constants

#include <avr/io.h>

#define LED_PIN PB0  // Define LED pin on PORTB0
#define DELAY_TIME 1000  // 1-second delay

void main() {
    DDRB |= (1 << LED_PIN);  // Set LED pin as output
    
    while(1) {
        PORTB ^= (1 << LED_PIN);  // Toggle LED
        _delay_ms(DELAY_TIME);
    }
}

Why Use #define?

• No extra memory usage (unlike const variables)
• Improves readability and maintainability
• Simplifies register access and bit manipulations

Creating Macros for Code Simplification

Macros allow defining short functions that are replaced before compilation.

Example: Creating a Macro for LED Toggling

#include <avr/io.h>

#define LED_TOGGLE() (PORTB ^= (1 << PB0))  // Macro to toggle LED

void main() {
    DDRB |= (1 << PB0);  // Set PB0 as output
    
    while(1) {
        LED_TOGGLE();  // Toggle LED
        _delay_ms(500);
    }
}

Advantages

• Avoids repetitive code
• Improves execution speed since there is no function call overhead
• Increases code clarity

Using Macros with Parameters

Macros can accept arguments, making them more flexible.

Example: Defining a Square Function

#define SQUARE(x) ((x) * (x))  // Macro to calculate square

void main() {
    int result = SQUARE(4);  // Expands to (4 * 4) = 16
    while(1);
}

Why Use Parentheses?

Without parentheses, an expression like:

#define SQUARE(x) x * x
int result = SQUARE(3 + 2);  // Expands to 3 + 2 * 3 + 2 = 3 + 6 + 2 = 11 (incorrect)

Adding parentheses ensures correct operator precedence.

Conditional Compilation Using #ifdef and #ifndef

Conditional compilation allows compiling only parts of the code based on predefined macros.

Example: Debug Mode

#include <avr/io.h>

#define DEBUG  // Uncomment this line to enable debugging

void main() {
    DDRB |= (1 << PB0);

#ifdef DEBUG
    PORTB |= (1 << PB0);  // Turn ON LED for debugging
#endif

    while(1);
}

How It Works

• If DEBUG is defined, the LED turns ON.
• If #define DEBUG is removed, the LED does not turn ON.

Including Header Files Using #include

Header files store reusable functions and macros.

Example: Creating a Custom Header File

Create a header file (led.h)

// led.h
#ifndef LED_H
#define LED_H

#define LED_PIN PB0
#define LED_ON() (PORTB |= (1 << LED_PIN))
#define LED_OFF() (PORTB &= ~(1 << LED_PIN))

#endif

Include it in the main program

#include <avr/io.h>
#include "led.h"  // Include custom header file

void main() {
    DDRB |= (1 << LED_PIN);

    while(1) {
        LED_ON();
        _delay_ms(500);
        LED_OFF();
        _delay_ms(500);
    }
}

Why Use Header Files?

• Organizes macros and function prototypes
• Prevents code duplication
• #ifndef LED_H prevents multiple inclusions

Using #pragma Directives

#pragma is used for compiler-specific settings.

Example: Disabling Warnings

#pragma GCC diagnostic ignored "-Wunused-variable"

void main() {
    int unusedVar;  // Normally, this would trigger a warning
    while(1);
}

Common Uses of #pragma

• #pragma config for AVR fuse settings
• #pragma pack for struct memory alignment

Using #error for Debugging

#error can stop compilation if conditions are not met.

Example: Checking Compiler Version

#if __AVR_ARCH__ < 6
#error "Upgrade to a newer AVR microcontroller!"
#endif

void main() {
    while(1);
}

When to Use #error?

• To prevent using unsupported hardware features
• To force code updates when compiler versions change

Best Practices for Preprocessor Usage

1. Use #define for Constants instead of const to save RAM.
2. Use Macros for Bit Manipulation to simplify register handling.
3. Use Header Files (#include) to keep code modular and readable.
4. Use Conditional Compilation (#ifdef) for debug/test modes.
5. Avoid Complex Macros that make debugging difficult.
6. Use #pragma Directives only when necessary.
7. Use #error for Critical Checks during compilation.

Summary

Using macros and preprocessor directives in C for AVR microcontrollers simplifies code, improves maintainability, and optimizes performance.