Pw_preprocessor_compiler

Macros
#define	PW_PACKED(declaration)   declaration __attribute__((packed))
#define	PW_USED   __attribute__((used))
	Marks a function or object as used, ensuring code for it is generated.
#define	PW_NO_PROLOGUE   __attribute__((naked))
#define	PW_PRINTF_FORMAT(format_index, parameter_index)    __attribute__((format(_PW_PRINTF_FORMAT_TYPE, format_index, parameter_index)))
#define	PW_PLACE_IN_SECTION(name)   __attribute__((section(name)))
	Places a variable in the specified linker section.
#define	PW_KEEP_IN_SECTION(name)   __attribute__((section(name), used))
#define	PW_NO_RETURN   __attribute__((noreturn))
#define	PW_NO_INLINE   __attribute__((noinline))
	Prevents the compiler from inlining a fuction.
#define	PW_UNREACHABLE   __builtin_unreachable()
#define	PW_NO_SANITIZE(check)
#define	PW_HAVE_ATTRIBUTE(x)   0
#define	PW_HAVE_CPP_ATTRIBUTE(x)   0
#define	PW_MODIFY_DIAGNOSTICS_PUSH()    _Pragma("GCC diagnostic push") _PW_REQUIRE_SEMICOLON
#define	PW_MODIFY_DIAGNOSTICS_POP()    _Pragma("GCC diagnostic pop") _PW_REQUIRE_SEMICOLON
#define	PW_MODIFY_DIAGNOSTIC(kind, option)    PW_PRAGMA(GCC diagnostic kind option) _PW_REQUIRE_SEMICOLON
#define	PW_MODIFY_DIAGNOSTIC_GCC(kind, option)    PW_MODIFY_DIAGNOSTIC(kind, option)
#define	PW_MODIFY_DIAGNOSTIC_CLANG(kind, option)   _PW_REQUIRE_SEMICOLON
#define	PW_PRAGMA(contents)   _Pragma(#contents)
#define	PW_WEAK   __attribute__((weak))
#define	PW_ALIAS(aliased_to)   __attribute__((weak, alias(#aliased_to)))
#define	PW_ATTRIBUTE_LIFETIME_BOUND
#define	PW_ADD_OVERFLOW(a, b, out)   __builtin_add_overflow(a, b, out)
#define	PW_SUB_OVERFLOW(a, b, out)   __builtin_sub_overflow(a, b, out)
#define	PW_MUL_OVERFLOW(a, b, out)   __builtin_mul_overflow(a, b, out)
#define	PW_VA_OPT_SUPPORTED()   _PW_VA_OPT_SUPPORTED()

Detailed Description

Macro Definition Documentation

PW_ADD_OVERFLOW

#define PW_ADD_OVERFLOW	(		a,
			b,
			out
	)		__builtin_add_overflow(a, b, out)

PW_ADD_OVERFLOW adds two integers while checking for overflow.

Returns true if the result of a + b overflows the type of out; otherwise stores the result in out and returns false.

It's recommended to use

embed:rst:inline :cpp:func:`pw::CheckedAdd` 

or

embed:rst:inline :cpp:func:`pw::CheckedIncrement` 

instead.

See also PW_CHECK_ADD.

PW_ALIAS

#define PW_ALIAS

(

aliased_to

)

__attribute__((weak, 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);

PW_ATTRIBUTE_LIFETIME_BOUND

#define PW_ATTRIBUTE_LIFETIME_BOUND

PW_ATTRIBUTE_LIFETIME_BOUND indicates that a resource owned by a function parameter or implicit object parameter is retained by the return value of the annotated function (or, for a parameter of a constructor, in the value of the constructed object). This attribute causes warnings to be produced if a temporary object does not live long enough.

When applied to a reference parameter, the referenced object is assumed to be retained by the return value of the function. When applied to a non-reference parameter (for example, a pointer or a class type), all temporaries referenced by the parameter are assumed to be retained by the return value of the function.

See also the upstream documentation: https://clang.llvm.org/docs/AttributeReference.html#lifetimebound

This is a copy of ABSL_ATTRIBUTE_LIFETIME_BOUND.

PW_HAVE_ATTRIBUTE

#define PW_HAVE_ATTRIBUTE

(

x

)

0

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_HAVE_CPP_ATTRIBUTE

#define PW_HAVE_CPP_ATTRIBUTE

(

x

)

0

A function-like feature checking macro that accepts C++11 style attributes. It is a wrapper around __has_cpp_attribute, which was introduced in the C++20 standard. It is supported by compilers even if C++20 is not in use. Evaluates to a non-zero constant integer if the C++ attribute is supported or 0 if not.

This is a copy of ABSL_HAVE_CPP_ATTRIBUTE.

PW_KEEP_IN_SECTION

#define PW_KEEP_IN_SECTION

(

name

)

__attribute__((section(name), used))

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_MODIFY_DIAGNOSTIC

#define PW_MODIFY_DIAGNOSTIC	(		kind,
			option
	)		PW_PRAGMA(GCC diagnostic kind option) _PW_REQUIRE_SEMICOLON

Changes how a diagnostic (warning or error) is handled. Most commonly used to disable warnings. PW_MODIFY_DIAGNOSTIC should be used between

embed:rst:inline :c:macro:`PW_MODIFY_DIAGNOSTICS_PUSH` 

and

embed:rst:inline :c:macro:`PW_MODIFY_DIAGNOSTICS_POP` 

statements to avoid applying the modifications too broadly.

kind may be warning, error, or ignored.

PW_MODIFY_DIAGNOSTIC_CLANG

#define PW_MODIFY_DIAGNOSTIC_CLANG	(		kind,
			option
	)		_PW_REQUIRE_SEMICOLON

Applies PW_MODIFY_DIAGNOSTIC only for Clang. This is useful for warnings that aren't supported by or don't need to be changed in other compilers.

PW_MODIFY_DIAGNOSTIC_GCC

#define PW_MODIFY_DIAGNOSTIC_GCC	(		kind,
			option
	)		PW_MODIFY_DIAGNOSTIC(kind, option)

Applies PW_MODIFY_DIAGNOSTIC only for GCC. This is useful for warnings that aren't supported by or don't need to be changed in other compilers.

PW_MODIFY_DIAGNOSTICS_POP

#define PW_MODIFY_DIAGNOSTICS_POP

(

)

_Pragma("GCC diagnostic pop") _PW_REQUIRE_SEMICOLON

embed:rst:inline :c:macro:`PW_MODIFY_DIAGNOSTIC` 

statements since the most recent

embed:rst:inline :c:macro:`PW_MODIFY_DIAGNOSTICS_PUSH` 

no longer apply after this statement.

PW_MODIFY_DIAGNOSTICS_PUSH

#define PW_MODIFY_DIAGNOSTICS_PUSH

(

)

_Pragma("GCC diagnostic push") _PW_REQUIRE_SEMICOLON

Starts a new group of

embed:rst:inline :c:macro:`PW_MODIFY_DIAGNOSTIC` 

statements. A

embed:rst:inline :c:macro:`PW_MODIFY_DIAGNOSTICS_POP` 

statement must follow.

PW_MUL_OVERFLOW

#define PW_MUL_OVERFLOW	(		a,
			b,
			out
	)		__builtin_mul_overflow(a, b, out)

PW_MUL_OVERFLOW multiplies two integers while checking for overflow.

Returns true if the result of a * b overflows the type of out; otherwise stores the result in out and returns false.

It's recommended to use

embed:rst:inline :cpp:func:`pw::CheckedMul` 

instead.

See also PW_CHECK_MUL.

PW_NO_PROLOGUE

#define PW_NO_PROLOGUE   __attribute__((naked))

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

PW_NO_RETURN

#define PW_NO_RETURN   __attribute__((noreturn))

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

PW_NO_RETURN void HandleAssertFailure(ErrorCode error_code);

PW_NO_SANITIZE

#define 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_PACKED

#define PW_PACKED

(

declaration

)

declaration __attribute__((packed))

Marks a struct or class as packed.

Use packed structs with extreme caution! Packed structs are rarely needed. Instead, define the struct and static_assert to verify that the size and alignement are as expected.

Packed structs should only be used to avoid standard padding or to force unaligned members when describing in-memory or wire format data structures. Packed struct members should NOT be accessed directly because they may be unaligned. Instead, memcpy the fields into variables. For example:

PW_PACKED(struct) PackedStruct {
  uint8_t a;
  uint32_t b;
  uint16_t c;
};
 
void UsePackedStruct(const PackedStruct& packed_struct) {
  uint8_t a;
  uint32_t b;
  uint16_t c;
  std::memcpy(&a, &packed_struct.a, sizeof(a));
  std::memcpy(&b, &packed_struct.b, sizeof(b));
  std::memcpy(&c, &packed_struct.c, sizeof(c));
}

PW_PRAGMA

#define PW_PRAGMA

(

contents

)

_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_PRINTF_FORMAT

#define PW_PRINTF_FORMAT	(		format_index,
			parameter_index
	)		__attribute__((format(_PW_PRINTF_FORMAT_TYPE, 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_SUB_OVERFLOW

#define PW_SUB_OVERFLOW	(		a,
			b,
			out
	)		__builtin_sub_overflow(a, b, out)

PW_SUB_OVERFLOW subtracts an integer from another while checking for overflow.

Returns true if the result of a - b overflows the type of out; otherwise stores the result in out and returns false.

It's recommended to use

embed:rst:inline :cpp:func:`pw::CheckedSub` 

or

embed:rst:inline :cpp:func:`pw::CheckedDecrement` 

instead.

See also PW_CHECK_SUB.

PW_UNREACHABLE

#define PW_UNREACHABLE   __builtin_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_VA_OPT_SUPPORTED

#define PW_VA_OPT_SUPPORTED

(

)

_PW_VA_OPT_SUPPORTED()

Evaluates to 1 if __VA_OPT__ is supported, regardless of the C or C++ standard in use.

PW_WEAK

#define PW_WEAK   __attribute__((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.
}