1. Home
2. Academy
3. Embedded C from Zero
4. Volume 15

15.1 #define and macros

The preprocessor runs before the compiler and works on text. It does not know about types, precedence, or how many times something should happen.

A macro is a name and some replacement text. When the preprocessor meets the name it pastes the text in, and that is the whole mechanism.

#define LED_PIN       5u
#define BIT(n)        (1u << (n))
#define SET(reg, m)   do { (reg) |= (m); } while (0)

void led_on(void)
{
    SET(odr, BIT(LED_PIN));
}

Run only the preprocessor with gcc -E and you can read exactly what the compiler will be handed:

unsigned odr;
void led_on(void)
{
    do { (odr) |= ((1u << (5u))); } while (0);
}
void extra_feature(void) { odr = 0u; }

Every macro is gone, replaced by its text. This command is worth remembering: when a macro is misbehaving, gcc -E ends the argument in seconds.

Trap one: brackets round the parameters

#define SQUARE_BAD(x)  x * x

1. brackets round the parameters
   #define SQUARE_BAD(x)  x * x
   SQUARE_BAD(2 + 3) expands to 2 + 3 * 2 + 3, which is 11
   SQUARE_OK(2 + 3)  expands to ((2 + 3) * (2 + 3)), which is 25

The argument is pasted in as text, so 2 + 3 lands either side of the * and multiplication binds tighter than addition. Brackets round each use of the parameter fix it.

Trap two: brackets round the whole thing

2. brackets round the whole expansion
   #define HALF_BAD(x)   (x) / 2
   12 / HALF_BAD(2) expands to 12 / (2) / 2, which is 3
   12 / HALF_OK(2)  expands to 12 / ((2) / 2), which is 12

The parameters were bracketed this time. The expansion itself was not, so the surrounding expression reached inside it. Both sets of brackets are needed, always.

Trap three: an argument used twice

#define MAX_MACRO(a, b) ((a) > (b) ? (a) : (b))

Every bracket is present. It is still wrong, because a appears twice in the replacement text, so whatever you pass happens twice.

3. an argument that appears twice
   int i = 5, j = 3;  MAX_MACRO(i++, j++) gave 6
   afterwards i is 7 and j is 4 - i was incremented twice
   the same with a function gave 5
   afterwards i is 6 and j is 4 - each was incremented once

The function gets it right because arguments are evaluated once, before the call. That is the general answer to this trap: use a function.

Trap four: more than one statement

#define TWO_THINGS_BAD(p)   led = (p); count++;
#define TWO_THINGS_OK(p)    do { led = (p); count++; } while (0)

Write if (x) TWO_THINGS_BAD(9); without brackets and only the first statement belongs to the if. The second runs unconditionally.

4. a macro holding two statements
   with brackets round it, the bad version works: led 9, count 1
   without them, count++ escapes the if: led 0, count 1
   the do-while version cannot escape:     led 0, count 0

The do { } while (0) wrapper looks strange and is exactly right: it makes the macro one statement, and it still needs the semicolon that everybody writes after it.

15.2 Include guards and header design

#include pastes a whole file in. An include guard stops that happening twice, which matters because most things cannot be defined twice.

Two headers that both include a third is all it takes, and in any real project that happens within a week.

static inline int doubled(int x)
{
    return 2 * x;
}

Include that twice in one file and the function is defined twice:

In file included from vol15_twice_fn.c:5:
vol15_inline.h:3:19: error: redefinition of 'doubled'

In file included from vol15_twice_fn.c:4:
vol15_inline.h:3:19: note: previous definition of 'doubled' with type 'int(int)'

Note the two "In file included from" lines. The compiler is telling you where each copy came from, which is how you find the pair of headers responsible.

The guard

#ifndef VOL15_GUARD_H
#define VOL15_GUARD_H

struct reading {
    int id;
    int value;
};

#endif /* VOL15_GUARD_H */

The first time through, VOL15_GUARD_H is not defined, so the body is used and the macro is defined. The second time, the macro exists, so everything down to #endif is skipped.

$ gcc -c vol15_twice_ok.c  # the guarded header, included twice
(compiled cleanly)

$ gcc -c vol15_twice.c     # unguarded header defining only a struct
(accepted: C23 allows an identical struct definition twice)

$ gcc -std=c11 -c vol15_twice.c   # the same file, older standard
vol15_noguard.h:3:8: error: redefinition of 'struct sensor'

What belongs in a header

A header is a promise, not an implementation. It should contain what other files need in order to call your code, and nothing else.

15.3 Conditional compilation

Conditional compilation does not skip code at run time. The branch not taken never reaches the compiler at all, so it costs no flash and no cycles.

#define BOARD_REV 2

#if BOARD_REV >= 2
void extra_feature(void) { odr = 0u; }
#else
void extra_feature(void) { odr = 1u; }
#endif

The preprocessor output from Module 1 shows what survived: one version of the function, with no trace that the other ever existed.

The two families

#ifdef NAME asks whether a macro is defined at all. #if EXPRESSION evaluates a constant expression. Prefer the second, because it can be wrong in useful ways.

#ifdef ENABLE_DEBUG
    log_state();
#endif

/* a typo in the name silently
   means "not defined", and the
   code vanishes with no warning */

#if ENABLE_DEBUG
    log_state();
#endif

/* with -Wundef, a typo is a
   warning rather than silence */

Keep it out of the middle of functions

Conditional compilation is at its worst scattered through logic, because the code you are reading is not the code being built.

void send(uint8_t b)
{
#if USE_DMA
    dma_queue(b);
#else
    uart_put(b);
#endif
#if LOG_LEVEL > 2
    log_byte(b);
#endif
}

#if USE_DMA
  #define send_byte dma_queue
#else
  #define send_byte uart_put
#endif

void send(uint8_t b)
{
    send_byte(b);
    log_byte(b);       /* empty when
                          logging is off */
}

The second version has one place where the choice is made, and the function itself reads the same in every build. A logging macro that expands to nothing is the usual way to make the second line free.

#if LOG_LEVEL > 2
  #define log_byte(b)  do { printf("byte %02X\n", (b)); } while (0)
#else
  #define log_byte(b)  do { (void)(b); } while (0)
#endif

The (void)(b) matters. Without it, a variable used only in logging becomes unused when logging is off, and -Wunused complains in exactly the build you were not testing.

15.4 Compiling, linking and object files

Four tools run in sequence, and each one leaves a file behind. Knowing which tool produced an error tells you where to look for it.

Run them by hand once and the sizes tell the story:

vol15_main.c       123 bytes
  main.i             199 bytes
  main.s             587 bytes
  main.o            1360 bytes
  program          15840 bytes

What an object file knows

A translation unit is one source file plus everything it included. The compiler sees one at a time, and so an object file knows only about itself.

                 U helper
0000000000000000 T main

T main means this file defines main. U helper means it uses helper and has no idea where it is. Volume 09 met these letters. The linker's job is to turn every U into an address.

The two link errors

$ gcc main.o -o program    # linking without lib.o
/usr/bin/x86_64-linux-gnu-ld.bfd: main.o: in function `main':
vol15_main.c:(.text+0xe): undefined reference to `helper'
collect2: error: ld returned 1 exit status

$ gcc main.o lib.o dup.o   # two definitions of the same function
/usr/bin/x86_64-linux-gnu-ld.bfd: dup.o: in function `helper':
vol15_dup.c:(.text+0x0): multiple definition of `helper'; lib.o:vol15_lib.c:(.text+0x0): first defined here
collect2: error: ld returned 1 exit status

Between them these two cover most link failures anyone meets. "Undefined reference" means you declared something and never defined it, or forgot to add a file to the build. "Multiple definition" means two files define the same name, which is usually a function that should have been static, or a variable defined in a header.

15.5 Makefiles

A Makefile records what depends on what. That is all it is, and it is why changing one file does not rebuild forty.

Each rule names a target, the things it is made from, and the command to make it.

CC      = arm-none-eabi-gcc
CFLAGS  = -mcpu=cortex-m4 -Os -Wall -Wextra -std=c11 -ffreestanding
LDFLAGS = -T link.ld -Wl,-Map=firmware.map

OBJS    = main.o gpio.o uart.o timer.o

firmware.elf: $(OBJS) link.ld
	$(CC) $(OBJS) $(LDFLAGS) -o $@

%.o: %.c
	$(CC) $(CFLAGS) -c $< -o $@

clean:
	rm -f $(OBJS) firmware.elf firmware.map

$@ is the target being built, $< is the first thing it is made from. The %.o: %.c rule says how to make any object file from the C file of the same name, so adding a source file means adding one word to OBJS.

Make compares timestamps. If uart.c is newer than uart.o, it rebuilds uart.o and then relinks. Nothing else is touched.

The dependency everybody forgets

That rule says uart.o depends on uart.c. It does not mention uart.h, or any other header. So edit a header, and nothing rebuilds - and you get a binary built from two different versions of the same structure.

The compiler can write the dependencies out for you:

CFLAGS += -MMD -MP
-include $(OBJS:.o=.d)

-MMD makes the compiler emit a .d file listing every header the source actually included, in Makefile syntax. The -include line reads them back. Now editing a header rebuilds exactly the files that included it.

15.6 Optimisation levels and what they break

An optimisation level changes how hard the compiler works, never what correct code means. If a program only works at -O0, the optimiser found a bug rather than causing one.

Here is the same file compiled five times and weighed:

level   text  data   bss
-O0      829     0     0
-O1      536     0     0
-Os      370     0     0
-O2      539     0     0
-O3     1835     0     0

Read that from the top. Level -O0 is largest because nothing is tidied, so every variable goes to the stack and comes back. Levels -O1 and -O2 get steadily better at removing work. -Os is smallest, because it is -O2 with the transformations that trade size for speed switched off.

And -O3 is five times the size of -Os. It unrolls loops and inlines aggressively. That is often faster on a desktop with megabytes of cache, and usually the wrong trade on a chip where flash is the scarce thing.

What optimisation exposes

The compiler is allowed to assume your program has no undefined behaviour. Where that assumption is false, higher levels make it visible.

1. A missing volatile, so a register read is cached or a write deleted - Volume 10 showed the assembly
2. A delay loop with no side effect, removed entirely
3. Reading a variable an interrupt writes, without volatile
4. Signed overflow, strict aliasing, or reading an uninitialised variable - all undefined, so all fair game
5. A race that was hidden by slower code, and appears when the window narrows

Every one of those is a bug in the source. The optimiser did not introduce it; it removed the padding that was hiding it.

What you learned

• The preprocessor is text substitution: gcc -E shows exactly what the compiler is handed
• A macro needs brackets round every parameter and round the whole expansion
• A macro argument that appears twice is evaluated twice, so prefer an inline function
• Wrap a multi-statement macro in do { } while (0) so it behaves like one statement
• Guard every header, because most things cannot be defined twice
• C23 now allows an identical struct definition twice, but guards are still essential
• Declare variables extern in headers and define them in exactly one .c file
• Code inside a false #if never reaches the compiler, so it costs nothing and is never checked
• -Wundef turns a typo in an #if from silence into a warning
• Preprocess, compile, assemble, link: the stage an error comes from tells you where to look
• Compiler errors name a line; linker errors name a symbol
• Make only knows the dependencies you declare, so use -MMD -MP to generate them
• Anything that make clean fixes is a dependency you have not declared
• -Os is the usual choice for firmware; -O3 made the same file five times larger
• If code only works at -O0, the optimiser exposed a bug rather than causing one

Practice

#define SCALE(v, pct)  (((v) * (pct)) / 100)

static inline uint32_t scale(uint32_t v, uint32_t pct)
{
    return (v * pct) / 100u;
}

extern int shared_counter;      /* it exists, somewhere */

int shared_counter;             /* here it is */

#ifndef LOG_H
#define LOG_H

#define LOG_NONE   0
#define LOG_ERROR  1
#define LOG_ALL    2

#ifndef LOG_LEVEL
  #define LOG_LEVEL LOG_ERROR        /* a default, so -Wundef stays quiet */
#endif

#if LOG_LEVEL >= LOG_ERROR
  #define log_error(...)  do { printf(__VA_ARGS__); } while (0)
#else
  #define log_error(...)  do { } while (0)
#endif

#if LOG_LEVEL >= LOG_ALL
  #define log_info(...)   do { printf(__VA_ARGS__); } while (0)
#else
  #define log_info(...)   do { } while (0)
#endif

#endif /* LOG_H */

CFLAGS += -MMD -MP

OBJS = main.o gpio.o uart.o timer.o
-include $(OBJS:.o=.d)

Interview corner

Next, Volume 16 turns to the habits that keep firmware working when nobody is watching. Defensive coding, error handling that does not lie, assertions, watchdogs, and a coding standard worth following.

Key words from this volume

Every word below has a plain-English entry in the glossary.

• Preprocessor
• Macro
• Include guard
• Conditional compilation
• Translation unit
• Object file
• Makefile
• Optimisation level