Compiler abstraction

Attributes and builtins, independent of the compiler. More...

Macros
#define	PBL_ALWAYS_INLINE   PBL_ALWAYS_INLINE_IMPL
	Inline the function at every call site.
#define	PBL_NOINLINE   PBL_NOINLINE_IMPL
	Never inline the function.
#define	PBL_NORETURN   PBL_NORETURN_IMPL
	The function does not return.
#define	PBL_NAKED   PBL_NAKED_IMPL
	The function has no prologue/epilogue; its body must be pure assembly.
#define	PBL_DEPRECATED   PBL_DEPRECATED_IMPL
	Warn on every use of the symbol.
#define	PBL_CONST_FUNC   PBL_CONST_FUNC_IMPL
	The function's result depends only on its arguments and it has no side effects.
#define	PBL_PURE_FUNC   PBL_PURE_FUNC_IMPL
	Like PBL_CONST_FUNC, but the function may also read global memory.
#define	PBL_OPTIMIZE(level)   PBL_OPTIMIZE_IMPL(level)
	Compile the function at the given optimization level, where supported.
#define	PBL_FORMAT_PRINTF(fmt, va)   PBL_FORMAT_PRINTF_IMPL(fmt, va)
	Check printf-style arguments.
#define	PBL_CLEANUP(func)   PBL_CLEANUP_IMPL(func)
	Call a function with a pointer to the variable when it goes out of scope.
#define	PBL_PACKED   PBL_PACKED_IMPL
	Lay out the struct/union without padding.
#define	PBL_ALIGNED(bytes)   PBL_ALIGNED_IMPL(bytes)
	Align the symbol or type.
#define	PBL_USED   PBL_USED_IMPL
	Keep the symbol even if it appears unreferenced.
#define	PBL_UNUSED   PBL_UNUSED_IMPL
	Do not warn if the symbol is unreferenced.
#define	PBL_WEAK   PBL_WEAK_IMPL
	Emit a weak symbol, overridable by a strong definition elsewhere.
#define	PBL_ALIAS(sym)   PBL_ALIAS_IMPL(sym)
	Make the symbol an alias of another one.
#define	PBL_EXTERNALLY_VISIBLE   PBL_EXTERNALLY_VISIBLE_IMPL
	Keep the symbol visible to code outside the compilation unit under LTO/whole-program builds.
#define	PBL_NOCOMMON   PBL_NOCOMMON_IMPL
	Emit the definition as a strong symbol instead of a common one.
#define	PBL_SECTION(name)   PBL_SECTION_IMPL(name)
	Place the symbol in a linker section.
#define	PBL_LIKELY(x)   PBL_LIKELY_IMPL(x)
	Branch prediction hint for a condition that is likely to hold.
#define	PBL_UNLIKELY(x)   PBL_UNLIKELY_IMPL(x)
	Branch prediction hint for a condition that is unlikely to hold.
#define	PBL_UNREACHABLE()   PBL_UNREACHABLE_IMPL()
	Mark a code path the compiler may assume is never reached.
#define	PBL_RETURN_ADDRESS(level)   PBL_RETURN_ADDRESS_IMPL(level)
	Return address of the current function or of its callers.
#define	PBL_TYPES_COMPATIBLE(a, b)   PBL_TYPES_COMPATIBLE_IMPL(a, b)
	Constant expression: 1 if the two types are compatible, else 0.
#define	PBL_CHOOSE_EXPR(cond, a, b)   PBL_CHOOSE_EXPR_IMPL(cond, a, b)
	Pick an expression from a constant condition without type-converting the other.
#define	PBL_CLZ(x)   PBL_CLZ_IMPL(x)
	Count leading zero bits.
#define	PBL_POPCOUNT(x)   PBL_POPCOUNT_IMPL(x)
	Count set bits.
#define	PBL_NO_SANITIZE_ADDRESS   PBL_NO_SANITIZE_ADDRESS_IMPL
	Keep AddressSanitizer off the object: no redzones around a global, e.g.
#define	PBL_ADD_OVERFLOW(a, b, r)   PBL_ADD_OVERFLOW_IMPL(a, b, r)
	Add, detecting overflow.
#define	PBL_MUL_OVERFLOW(a, b, r)   PBL_MUL_OVERFLOW_IMPL(a, b, r)
	Multiply, detecting overflow.
#define	PBL_BSWAP16(x)   PBL_BSWAP16_IMPL(x)
	Reverse the bytes of a 16-bit value.
#define	PBL_BSWAP32(x)   PBL_BSWAP32_IMPL(x)
	Reverse the bytes of a 32-bit value.

Detailed Description

Attributes and builtins, independent of the compiler.

The only place the tree may spell compiler specifics: code outside pbl/kernel/compiler/ must not use __attribute__ or __builtin_* directly. Each macro expands to a *_IMPL counterpart from compiler/gcc.h or compiler/clang.h; attributes a compiler does not implement expand to nothing. Shipped with the SDK.

typedef struct PBL_PACKED {
  uint16_t id;
  uint32_t value;
} Record;
 
PBL_NORETURN void fatal(const char *fmt, ...) PBL_FORMAT_PRINTF(1, 2);
 
if (PBL_UNLIKELY(len > MAX_LEN)) {
  return -EINVAL;
}

Macro Definition Documentation

PBL_ADD_OVERFLOW

#define PBL_ADD_OVERFLOW	(		a,
			b,
			r
	)		PBL_ADD_OVERFLOW_IMPL(a, b, r)

Add, detecting overflow.

Prefer the typed helpers of pbl/util/math.h.

Parameters

a	First operand.
b	Second operand.
r	Where the result goes, wrapped around on overflow.

Returns

true if the result overflowed the type of r.

PBL_ALIAS

#define PBL_ALIAS

(

sym

)

PBL_ALIAS_IMPL(sym)

Make the symbol an alias of another one.

Combine with PBL_WEAK for an overridable default handler.

Parameters

sym	Target symbol name, as a string.

PBL_ALIGNED

#define PBL_ALIGNED

(

bytes

)

PBL_ALIGNED_IMPL(bytes)

Align the symbol or type.

Parameters

bytes

Alignment in bytes, a power of two.

PBL_ALWAYS_INLINE

#define PBL_ALWAYS_INLINE   PBL_ALWAYS_INLINE_IMPL

Inline the function at every call site.

Expands to the inline keyword as well.

PBL_BSWAP16

#define PBL_BSWAP16

(

x

)

PBL_BSWAP16_IMPL(x)

Reverse the bytes of a 16-bit value.

Parameters

x

Value.

PBL_BSWAP32

#define PBL_BSWAP32

(

x

)

PBL_BSWAP32_IMPL(x)

Reverse the bytes of a 32-bit value.

Parameters

x

Value.

PBL_CHOOSE_EXPR

#define PBL_CHOOSE_EXPR	(		cond,
			a,
			b
	)		PBL_CHOOSE_EXPR_IMPL(cond, a, b)

Pick an expression from a constant condition without type-converting the other.

Parameters

cond	Constant condition.
a	Result if cond is non-zero.
b	Result if cond is zero.

PBL_CLEANUP

#define PBL_CLEANUP

(

func

)

PBL_CLEANUP_IMPL(func)

Call a function with a pointer to the variable when it goes out of scope.

Parameters

func	Function taking a pointer to the variable's type.

PBL_CLZ

#define PBL_CLZ

(

x

)

PBL_CLZ_IMPL(x)

Count leading zero bits.

Parameters

x	Unsigned int; undefined for 0.

PBL_CONST_FUNC

#define PBL_CONST_FUNC   PBL_CONST_FUNC_IMPL

The function's result depends only on its arguments and it has no side effects.

PBL_DEPRECATED

#define PBL_DEPRECATED   PBL_DEPRECATED_IMPL

Warn on every use of the symbol.

PBL_EXTERNALLY_VISIBLE

#define PBL_EXTERNALLY_VISIBLE   PBL_EXTERNALLY_VISIBLE_IMPL

Keep the symbol visible to code outside the compilation unit under LTO/whole-program builds.

A no-op with Clang.

PBL_FORMAT_PRINTF

#define PBL_FORMAT_PRINTF	(		fmt,
			va
	)		PBL_FORMAT_PRINTF_IMPL(fmt, va)

Check printf-style arguments.

Parameters

fmt	1-based index of the format string parameter.
va	1-based index of the first variadic parameter, 0 for a va_list function.

PBL_LIKELY

#define PBL_LIKELY

(

x

)

PBL_LIKELY_IMPL(x)

Branch prediction hint for a condition that is likely to hold.

Parameters

x	Condition.

PBL_MUL_OVERFLOW

#define PBL_MUL_OVERFLOW	(		a,
			b,
			r
	)		PBL_MUL_OVERFLOW_IMPL(a, b, r)

Multiply, detecting overflow.

Prefer the typed helpers of pbl/util/math.h.

Parameters

a	First operand.
b	Second operand.
r	Where the result goes, wrapped around on overflow.

Returns

true if the result overflowed the type of r.

PBL_NAKED

#define PBL_NAKED   PBL_NAKED_IMPL

The function has no prologue/epilogue; its body must be pure assembly.

PBL_NO_SANITIZE_ADDRESS

#define PBL_NO_SANITIZE_ADDRESS   PBL_NO_SANITIZE_ADDRESS_IMPL

Keep AddressSanitizer off the object: no redzones around a global, e.g.

one that must sit next to its neighbours in a section.

PBL_NOCOMMON

#define PBL_NOCOMMON   PBL_NOCOMMON_IMPL

Emit the definition as a strong symbol instead of a common one.

PBL_NOINLINE

#define PBL_NOINLINE   PBL_NOINLINE_IMPL

Never inline the function.

PBL_NORETURN

#define PBL_NORETURN   PBL_NORETURN_IMPL

The function does not return.

Combine with the void return type.

PBL_OPTIMIZE

#define PBL_OPTIMIZE

(

level

)

PBL_OPTIMIZE_IMPL(level)

Compile the function at the given optimization level, where supported.

A no-op with Clang.

Parameters

level

Level as a string, e.g. "O2".

PBL_PACKED

#define PBL_PACKED   PBL_PACKED_IMPL

Lay out the struct/union without padding.

PBL_POPCOUNT

#define PBL_POPCOUNT

(

x

)

PBL_POPCOUNT_IMPL(x)

Count set bits.

Parameters

x	Unsigned int.

PBL_PURE_FUNC

#define PBL_PURE_FUNC   PBL_PURE_FUNC_IMPL

Like PBL_CONST_FUNC, but the function may also read global memory.

PBL_RETURN_ADDRESS

#define PBL_RETURN_ADDRESS

(

level

)

PBL_RETURN_ADDRESS_IMPL(level)

Return address of the current function or of its callers.

Parameters

level

0 for the current function, 1 for its caller, and so on; a constant.

PBL_SECTION

#define PBL_SECTION

(

name

)

PBL_SECTION_IMPL(name)

Place the symbol in a linker section.

A no-op in unit tests and in builds linked without the firmware linker script (PBL_NO_LINKER_SCRIPT), where nothing would gather the sections.

Parameters

name	Section name, as a string.

PBL_TYPES_COMPATIBLE

#define PBL_TYPES_COMPATIBLE	(		a,
			b
	)		PBL_TYPES_COMPATIBLE_IMPL(a, b)

Constant expression: 1 if the two types are compatible, else 0.

Parameters

a	First type.
b	Second type.

PBL_UNLIKELY

#define PBL_UNLIKELY

(

x

)

PBL_UNLIKELY_IMPL(x)

Branch prediction hint for a condition that is unlikely to hold.

Parameters

x	Condition.

PBL_UNREACHABLE

#define PBL_UNREACHABLE

(

)

PBL_UNREACHABLE_IMPL()

Mark a code path the compiler may assume is never reached.

PBL_UNUSED

#define PBL_UNUSED   PBL_UNUSED_IMPL

Do not warn if the symbol is unreferenced.

PBL_USED

#define PBL_USED   PBL_USED_IMPL

Keep the symbol even if it appears unreferenced.

PBL_WEAK

#define PBL_WEAK   PBL_WEAK_IMPL

Emit a weak symbol, overridable by a strong definition elsewhere.