pw_preprocessor

The preprocessor module provides various helpful preprocessor macros.

Compatibility

C and C++

Headers

The preprocessor module provides several headers.

pw_preprocessor/arguments.h

Defines macros for handling variadic arguments to function-like macros. Macros include the following:

PW_DELEGATE_BY_ARG_COUNT(name, ...)

Selects and invokes a macro based on the number of arguments provided. Expands to <name><arg_count>(...). For example, PW_DELEGATE_BY_ARG_COUNT(foo_, 1, 2, 3) expands to foo_3(1, 2, 3).

This example shows how PW_DELEGATE_BY_ARG_COUNT could be used to log a customized message based on the number of arguments provided.

#define ARG_PRINT(...)  PW_DELEGATE_BY_ARG_COUNT(_ARG_PRINT, __VA_ARGS__)
#define _ARG_PRINT0(a)        LOG_INFO("nothing!")
#define _ARG_PRINT1(a)        LOG_INFO("1 arg: %s", a)
#define _ARG_PRINT2(a, b)     LOG_INFO("2 args: %s, %s", a, b)
#define _ARG_PRINT3(a, b, c)  LOG_INFO("3 args: %s, %s, %s", a, b, c)

When used, ARG_PRINT expands to the _ARG_PRINT# macro corresponding to the number of arguments.

ARG_PRINT();               // Outputs: nothing!
ARG_PRINT("a");            // Outputs: 1 arg: a
ARG_PRINT("a", "b");       // Outputs: 2 args: a, b
ARG_PRINT("a", "b", "c");  // Outputs: 3 args: a, b, c
PW_COMMA_ARGS(...)

Expands to a comma followed by the arguments if any arguments are provided. Otherwise, expands to nothing. If the final argument is empty, it is omitted. This is useful when passing __VA_ARGS__ to a variadic function or template parameter list, since it removes the extra comma when no arguments are provided. PW_COMMA_ARGS must NOT be used when invoking a macro from another macro.

For example. PW_COMMA_ARGS(1, 2, 3), expands to , 1, 2, 3, while PW_COMMA_ARGS() expands to nothing. PW_COMMA_ARGS(1, 2, ) expands to , 1, 2.

pw_preprocessor/boolean.h

Defines macros for boolean logic on literal 1s and 0s. This is useful for situations when a literal is needed to build the name of a function or macro.

pw_preprocessor/compiler.h

Macros for compiler-specific features, such as attributes or builtins.

PW_PACKED(declaration)

Marks a struct or class as packed.

PW_USED

Marks a function or object as used, ensuring code for it is generated.

PW_NO_PROLOGUE

Prevents generation of a prologue or epilogue for a function. This is helpful when implementing the function in assembly.

PW_PRINTF_FORMAT(format_index, parameter_index)

Marks that a function declaration takes a printf-style format string and variadic arguments. This allows the compiler to perform check the validity of the format string and arguments. This macro must only be on the function declaration, not the definition.

The format_index is index of the format string parameter and parameter_index is the starting index of the variadic arguments. Indices start at 1. For C++ class member functions, add one to the index to account for the implicit this parameter.

This example shows a function where the format string is argument 2 and the varargs start at argument 3.

int PrintfStyleFunction(char* buffer,
                        const char* fmt, ...) PW_PRINTF_FORMAT(2,3);

int PrintfStyleFunction(char* buffer, const char* fmt, ...) {
  ... implementation here ...
}
PW_PLACE_IN_SECTION(name)

Places a variable in the specified linker section.

PW_KEEP_IN_SECTION(name)

Places a variable in the specified linker section and directs the compiler to keep the variable, even if it is not used. Depending on the linker options, the linker may still remove this section if it is not declared in the linker script and marked KEEP.

PW_NO_RETURN

Indicate to the compiler that the annotated function won’t return. Example:

PW_NO_RETURN void HandleAssertFailure(ErrorCode error_code);
PW_NO_INLINE

Prevents the compiler from inlining a fuction.

PW_UNREACHABLE

Indicate to the compiler that the given section of code will not be reached. Example:

int main() {
  InitializeBoard();
  vendor_StartScheduler();  // Note: vendor forgot noreturn attribute.
  PW_UNREACHABLE;
}
PW_NO_SANITIZE(check)

Indicate to a sanitizer compiler runtime to skip the named check in the associated function. Example:

uint32_t djb2(const void* buf, size_t len)
    PW_NO_SANITIZE("unsigned-integer-overflow"){
  uint32_t hash = 5381;
  const uint8_t* u8 = static_cast<const uint8_t*>(buf);
  for (size_t i = 0; i < len; ++i) {
    hash = (hash * 33) + u8[i]; // hash * 33 + c
  }
  return hash;
}
PW_HAVE_ATTRIBUTE(x)

Wrapper around __has_attribute, which is defined by GCC 5+ and Clang and evaluates to a non zero constant integer if the attribute is supported or 0 if not.

PW_PRAGMA(contents)

Expands to a _Pragma with the contents as a string. _Pragma must take a single string literal; this can be used to construct a _Pragma argument.

PW_WEAK

Marks a function or object as weak, allowing the definition to be overriden.

This can be useful when supporting third-party SDKs which may conditionally compile in code, for example:

PW_WEAK void SysTick_Handler(void) {
  // Default interrupt handler that might be overriden.
}
PW_ALIAS(aliased_to)

Marks a weak function as an alias to another, allowing the definition to be given a default and overriden.

This can be useful when supporting third-party SDKs which may conditionally compile in code, for example:

// Driver handler replaced with default unless overridden.
void USART_DriverHandler(void) PW_ALIAS(DefaultDriverHandler);

Modifying compiler diagnostics

pw_preprocessor/compiler.h provides macros for enabling or disabling compiler diagnostics (warnings or errors).

PW_MODIFY_DIAGNOSTICS_PUSH()

Starts a new group of PW_MODIFY_DIAGNOSTIC statements. A PW_MODIFY_DIAGNOSTICS_POP statement must follow.

PW_MODIFY_DIAGNOSTICS_POP()

PW_MODIFY_DIAGNOSTIC statements since the most recent PW_MODIFY_DIAGNOSTICS_PUSH no longer apply after this statement.

PW_MODIFY_DIAGNOSTIC(kind, option)

Changes how a diagnostic (warning or error) is handled. Most commonly used to disable warnings. PW_MODIFY_DIAGNOSTIC should be used between PW_MODIFY_DIAGNOSTICS_PUSH and PW_MODIFY_DIAGNOSTICS_POP statements to avoid applying the modifications too broadly.

kind may be warning, error, or ignored.

These macros can be used to disable warnings for precise sections of code, even a single line if necessary.

PW_MODIFY_DIAGNOSTICS_PUSH();
PW_MODIFY_DIAGNOSTIC(ignored, "-Wunused-variable");

static int this_variable_is_never_used;

PW_MODIFY_DIAGNOSTICS_POP();

Tip

PW_MODIFY_DIAGNOSTIC and related macros should rarely be used. Whenever possible, fix the underlying issues about which the compiler is warning, rather than silencing the diagnostics.

pw_preprocessor/concat.h

Defines the PW_CONCAT(...) macro, which expands its arguments if they are macros and token pastes the results. This can be used for building names of classes, variables, macros, etc.

pw_preprocessor/util.h

General purpose, useful macros.

  • PW_ARRAY_SIZE(array) – calculates the size of a C array

  • PW_STRINGIFY(...) – expands its arguments as macros and converts them to a string literal

  • PW_EXTERN_C – declares a name to be extern "C" in C++; expands to nothing in C

  • PW_EXTERN_C_START / PW_EXTERN_C_END – declares an extern "C" { } block in C++; expands to nothing in C