NAME
attribute —
non-standard compiler
attribute extensions
SYNOPSIS
#include <sys/cdefs.h>
__dead
__pure
__constfunc
__noinline
__unused
__used
__diagused
__debugused
__packed
__aligned(
x);
__section(
section);
__read_mostly
__cacheline_aligned
__predict_true(
exp);
__predict_false(
exp);
DESCRIPTION
As an extension to the C standard, some compilers allow non-standard attributes
to be associated with functions, variables, or types, to modify some aspect of
the way the compiler treats the associated item. The GNU Compiler Collection
(GCC), and LLVM/Clang, use the
__attribute__ syntax for such
attributes, but different versions of the compilers support different
attributes, and other compilers may use entirely different syntax.
NetBSD code should usually avoid direct use of the
__attribute__ or similar syntax provided by specific
compilers. Instead,
NetBSD's
<sys/cdefs.h> header file provides
several attribute macros in a namespace reserved for the implementation
(beginning with ‘
__
’), that expand to the
appropriate syntax for the compiler that is in use.
ATTRIBUTES
-
-
- __dead
- Certain functions, such as
abort(3) and
exit(3), can never return any
value. When such a function is declared with __dead,
certain optimizations are possible. Obviously a __dead
function can never have return type other than
void.
-
-
- __pure
- A __pure function is defined to be one
that has no effects except the return value, which is assumed to depend
only on the function parameters and/or global variables. Any access to
parameters and/or global variables must also be read-only. A function that
depends on volatile memory, or other comparable system resource that can
change between two consecutive calls, can never be
__pure. Many
math(3) functions satisfy the
definition of a __pure function, at least in theory.
Other examples include
strlen(3) and
strcmp(3).
-
-
- __constfunc
- A “const function” is a stricter variant of
“pure functions”. In addition to the restrictions of pure
functions, a function declared with __constfunc can
never access global variables nor take pointers as parameters. The return
value of these functions must depend only on the passed-by-value
parameters. Note also that a function that calls non-const functions can
not be __constfunc. The canonical example of a const
function would be abs(3). As
with pure functions, certain micro-optimizations are possible for
functions declared with __constfunc.
-
-
- __noinline
- Sometimes it is known that inlining is undesirable or that
a function will perform incorrectly when inlined. The
__noinline macro expands to a function attribute that
prevents the compiler from inlining the function, irrespective of whether
the function was declared with the inline keyword. The
attribute takes precedence over all other compiler options related to
inlining.
-
-
- __unused
- Marking an unused function with the
__unused macro inhibits warnings that a function is
defined but not used. Marking a variable with the
__unused macro inhibits warnings that the variable is
unused, or that it is set but never read.
-
-
- __used
- The __used macro expands to an attribute
that informs the compiler that a static variable or function is to be
always retained in the object file even if it is unreferenced.
-
-
- __diagused
- The __diagused macro expands to an
attribute that informs the compiler that a variable or function is used
only in diagnostic code, and may be unused in non-diagnostic code.
In the kernel, variables that are used when
DIAGNOSTIC
is defined, but unused when
DIAGNOSTIC
is not defined, may be declared with
__diagused. In userland, variables that are used when
NDEBUG
is not defined, but unused when
NDEBUG
is defined, may be declared with
__diagused.
Variables used only in
assert(3) or
KASSERT(9) macros are
likely candidates for being declared with
__diagused.
-
-
- __debugused
- The __debugused macro expands to an
attribute that informs the compiler that a variable or function is used
only in debug code, and may be unused in non-debug code.
In either the kernel or userland, variables that are used when
DEBUG
is defined, but unused when
DEBUG
is not defined, may be declared with
__debugused.
In the kernel, variables used only in
KDASSERT(9) macros are
likely candidates for being declared with __debugused.
There is no established convention for the use of
DEBUG
in userland code.
-
-
- __packed
- The __packed macro expands to an
attribute that forces a variable or structure field to have the smallest
possible alignment, potentially disregarding architecture specific
alignment requirements. The smallest possible alignment is effectively one
byte for variables and one bit for fields. If specified on a
struct or union, all variables
therein are also packed. The __packed macro is often
useful when dealing with data that is in a particular static format on the
disk, wire, or memory.
-
-
- __aligned(x)
- The __aligned() macro expands to an
attribute that specifies the minimum alignment in bytes for a variable,
structure field, or function. In other words, the specified object should
have an alignment of at least x bytes, as opposed to
the minimum alignment requirements dictated by the architecture and the
ABI. Possible use cases include:
- Mixing assembly and C code.
- Dealing with hardware that may impose alignment
requirements greater than the architecture itself.
- Using instructions that may impose special alignment
requirements. Typical example would be alignment of frequently used
objects along processor cache lines.
Note that when used with functions, structures, or structure members,
__aligned() can only be used to increase the alignment.
If the macro is however used as part of a typedef,
the alignment can both increase and decrease. Otherwise it is only
possible to decrease the alignment for variables and fields by using the
__packed macro. The effectiveness of
__aligned() is largely dependent on the linker. The
__alignof__(3) operator
can be used to examine the alignment.
-
-
- __section(section)
- The __section() macro expands to an
attribute that specifies a particular section to
which a variable or function should be placed. Normally the compiler
places the generated objects to sections such as “data” or
“text”. By using __section(), it is possible
to override this behavior, perhaps in order to place some variables into
particular sections specific to unique hardware.
-
-
- __read_mostly
- The __read_mostly macro uses
__section() to place a variable or function into the
“.data.read_mostly” section of the (kernel)
elf(5). The use of
__read_mostly allows infrequently modified data to be
grouped together; it is expected that the cachelines of rarely and
frequently modified data structures are this way separated. Candidates for
__read_mostly include variables that are initialized
once, read very often, and seldom written to.
-
-
- __cacheline_aligned
- The __cacheline_aligned macro behaves
like __read_mostly, but the used section is
“.data.cacheline_aligned” instead. It also uses
__aligned() to set the minimum alignment into a
predefined coherency unit. This should ensure that frequently used data
structures are aligned on cacheline boundaries. Both
__cacheline_aligned and __read_mostly
are only available for the kernel.
-
-
- __predict_true
- A branch is generally defined to be a conditional execution
of a program depending on whether a certain flow control mechanism is
altered. Typical example would be a “if-then-else” sequence
used in high-level languages or a jump instruction used in machine-level
code. A branch prediction would then be defined as an attempt to guess
whether a conditional branch will be taken.
The macros __predict_true() and
__predict_false() annotate the likelihood of whether a
branch will evaluate to true or false. The rationale is to improve
instruction pipelining. Semantically __predict_true
expects that the integral expression exp yields
nonzero.
-
-
- __predict_false
- The __predict_false expands to an
attribute that instructs the compiler to predict that a given branch will
be likely false. As programmers are notoriously bad at predicting the
likely behavior of their code, profiling and empirical evidence should
precede the use of __predict_false and
__predict_true.
SEE ALSO
clang(1),
gcc(1),
__builtin_object_size(3),
cdefs(3),
c(7)
CAVEATS
It goes without saying that portable applications should steer clear from
non-standard extensions specific to any given compiler. Even when portability
is not a concern, use these macros sparsely and wisely.