393 lines
11 KiB
Groff
393 lines
11 KiB
Groff
.\" $NetBSD: attribute.3,v 1.18 2018/09/14 20:53:49 christos Exp $
|
|
.\"
|
|
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Jukka Ruohonen.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd September 14, 2018
|
|
.Dt ATTRIBUTE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm attribute
|
|
.Nd non-standard compiler attribute extensions
|
|
.Sh SYNOPSIS
|
|
.In sys/cdefs.h
|
|
.Pp
|
|
.Ic __dead
|
|
.Pp
|
|
.Ic __pure
|
|
.Pp
|
|
.Ic __constfunc
|
|
.Pp
|
|
.Ic __noinline
|
|
.Pp
|
|
.Ic __unused
|
|
.Pp
|
|
.Ic __used
|
|
.Pp
|
|
.Ic __diagused
|
|
.Pp
|
|
.Ic __debugused
|
|
.Pp
|
|
.Ic __packed
|
|
.Pp
|
|
.Fn __aligned "x"
|
|
.Fn __section "section"
|
|
.Pp
|
|
.Ic __read_mostly
|
|
.Pp
|
|
.Ic __cacheline_aligned
|
|
.Pp
|
|
.Fn __predict_true "exp"
|
|
.Pp
|
|
.Fn __predict_false "exp"
|
|
.Pp
|
|
.Fn __printflike "fmtarg" "firstvararg"
|
|
.Pp
|
|
.Fn __sysloglike "fmtarg" "firstvararg"
|
|
.Sh 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
|
|
.Tn GNU
|
|
Compiler Collection
|
|
.Pq Tn GCC ,
|
|
and
|
|
.Tn LLVM/Clang ,
|
|
use the
|
|
.Em __attribute__
|
|
syntax for such attributes,
|
|
but different versions of the compilers support different attributes,
|
|
and other compilers may use entirely different syntax.
|
|
.Pp
|
|
.Nx
|
|
code should usually avoid direct use of the
|
|
.Em __attribute__
|
|
or similar syntax provided by specific compilers.
|
|
Instead,
|
|
.Nx Ap s
|
|
.In sys/cdefs.h
|
|
header file
|
|
provides several attribute macros in a namespace
|
|
reserved for the implementation (beginning with
|
|
.Ql __ ) ,
|
|
that expand to the appropriate syntax for the compiler that is in use.
|
|
.Sh ATTRIBUTES
|
|
.Bl -tag -width abc
|
|
.It Ic __dead
|
|
Certain functions, such as
|
|
.Xr abort 3
|
|
and
|
|
.Xr exit 3 ,
|
|
can never return.
|
|
When such a function is declared with
|
|
.Ic __dead ,
|
|
certain optimizations are possible and warnings sensitive to the code flow graph
|
|
may be pruned.
|
|
Obviously a
|
|
.Ic __dead
|
|
function can never have return type other than
|
|
.Vt void .
|
|
.It Ic __pure
|
|
A
|
|
.Ic __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
|
|
.Ic __pure .
|
|
Many
|
|
.Xr math 3
|
|
functions satisfy the definition of a
|
|
.Ic __pure
|
|
function, at least in theory.
|
|
Other examples include
|
|
.Xr strlen 3
|
|
and
|
|
.Xr strcmp 3 .
|
|
.It Ic __constfunc
|
|
A
|
|
.Dq const function
|
|
is a stricter variant of
|
|
.Dq pure functions .
|
|
In addition to the restrictions of pure functions, a function declared with
|
|
.Ic __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
|
|
.Ic __constfunc .
|
|
The canonical example of a const function would be
|
|
.Xr abs 3 .
|
|
As with pure functions,
|
|
certain micro-optimizations are possible for functions declared with
|
|
.Ic __constfunc .
|
|
.It Ic __noinline
|
|
Sometimes it is known that inlining is undesirable or that
|
|
a function will perform incorrectly when inlined.
|
|
The
|
|
.Ic __noinline
|
|
macro expands to a function attribute that prevents
|
|
the compiler from inlining the function, irrespective
|
|
of whether the function was declared with the
|
|
.Em inline
|
|
keyword.
|
|
The attribute takes precedence over all
|
|
other compiler options related to inlining.
|
|
.It Ic __unused
|
|
Marking an unused function with the
|
|
.Ic __unused
|
|
macro inhibits warnings that a function is defined but not used.
|
|
Marking a variable with the
|
|
.Ic __unused
|
|
macro inhibits warnings that the variable is unused,
|
|
or that it is set but never read.
|
|
.It Ic __used
|
|
The
|
|
.Ic __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.
|
|
.It Ic __diagused
|
|
The
|
|
.Ic __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.
|
|
.Pp
|
|
In the kernel, variables that are used when
|
|
.Dv DIAGNOSTIC
|
|
is defined, but unused when
|
|
.Dv DIAGNOSTIC
|
|
is not defined, may be declared with
|
|
.Ic __diagused .
|
|
In userland, variables that are used when
|
|
.Dv NDEBUG
|
|
is not defined, but unused when
|
|
.Dv NDEBUG
|
|
is defined, may be declared with
|
|
.Ic __diagused .
|
|
.Pp
|
|
Variables used only in
|
|
.Xr assert 3
|
|
or
|
|
.Xr KASSERT 9
|
|
macros are likely candidates for being declared with
|
|
.Ic __diagused .
|
|
.It Ic __debugused
|
|
The
|
|
.Ic __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.
|
|
.Pp
|
|
In either the kernel or userland, variables that are used when
|
|
.Dv DEBUG
|
|
is defined, but unused when
|
|
.Dv DEBUG
|
|
is not defined, may be declared with
|
|
.Ic __debugused .
|
|
.Pp
|
|
In the kernel, variables used only in
|
|
.Xr KDASSERT 9
|
|
macros are likely candidates for being declared with
|
|
.Ic __debugused .
|
|
There is no established convention for the use of
|
|
.Dv DEBUG
|
|
in userland code.
|
|
.It Ic __packed
|
|
The
|
|
.Ic __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
|
|
.Vt struct
|
|
or
|
|
.Vt union ,
|
|
all variables therein are also packed.
|
|
The
|
|
.Ic __packed
|
|
macro is often useful when dealing with data that
|
|
is in a particular static format on the disk, wire, or memory.
|
|
.It Fn __aligned "x"
|
|
The
|
|
.Fn __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
|
|
.Fa x
|
|
bytes, as opposed to the minimum alignment requirements dictated
|
|
by the architecture and the
|
|
.Tn ABI .
|
|
Possible use cases include:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
Mixing assembly and C code.
|
|
.It
|
|
Dealing with hardware that may impose alignment requirements
|
|
greater than the architecture itself.
|
|
.It
|
|
Using instructions that may impose special alignment requirements.
|
|
Typical example would be alignment of frequently used objects along
|
|
processor cache lines.
|
|
.El
|
|
.Pp
|
|
Note that when used with functions, structures, or structure members,
|
|
.Fn __aligned
|
|
can only be used to increase the alignment.
|
|
If the macro is however used as part of a
|
|
.Vt typedef ,
|
|
the alignment can both increase and decrease.
|
|
Otherwise it is only possible to decrease the alignment
|
|
for variables and fields by using the
|
|
.Ic __packed
|
|
macro.
|
|
The effectiveness of
|
|
.Fn __aligned
|
|
is largely dependent on the linker.
|
|
The
|
|
.Xr __alignof__ 3
|
|
operator can be used to examine the alignment.
|
|
.It Fn __section "section"
|
|
The
|
|
.Fn __section
|
|
macro expands to an attribute that specifies a particular
|
|
.Fa section
|
|
to which a variable or function should be placed.
|
|
Normally the compiler places the generated objects to sections such as
|
|
.Dq data
|
|
or
|
|
.Dq text .
|
|
By using
|
|
.Fn __section ,
|
|
it is possible to override this behavior, perhaps in order to place
|
|
some variables into particular sections specific to unique hardware.
|
|
.It Ic __read_mostly
|
|
The
|
|
.Ic __read_mostly
|
|
macro uses
|
|
.Fn __section
|
|
to place a variable or function into the
|
|
.Dq .data.read_mostly
|
|
section of the (kernel)
|
|
.Xr elf 5 .
|
|
The use of
|
|
.Ic __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
|
|
.Ic __read_mostly
|
|
include variables that are initialized once,
|
|
read very often, and seldom written to.
|
|
.It Ic __cacheline_aligned
|
|
The
|
|
.Ic __cacheline_aligned
|
|
macro behaves like
|
|
.Ic __read_mostly ,
|
|
but the used section is
|
|
.Dq .data.cacheline_aligned
|
|
instead.
|
|
It also uses
|
|
.Fn __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
|
|
.Ic __cacheline_aligned
|
|
and
|
|
.Ic __read_mostly
|
|
are only available for the kernel.
|
|
.It Ic __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
|
|
.Dq 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.
|
|
.Pp
|
|
The macros
|
|
.Fn __predict_true
|
|
and
|
|
.Fn __predict_false
|
|
annotate the likelihood of whether
|
|
a branch will evaluate to true or false.
|
|
The rationale is to improve instruction pipelining.
|
|
Semantically
|
|
.Ic __predict_true
|
|
expects that the integral expression
|
|
.Fa exp
|
|
yields nonzero.
|
|
.It Ic __predict_false
|
|
The
|
|
.Ic __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
|
|
.Ic __predict_false
|
|
and
|
|
.Ic __predict_true .
|
|
.It Fn __printflike "fmtarg" "firstvararg"
|
|
Marks a function as taking printf-like arguments.
|
|
.Fa fmtarg
|
|
is the index of the format string in the argument list, and
|
|
.Fa firstvararg
|
|
is the index of the first item of the vararg list.
|
|
.It Fn __sysloglike "fmtarg" "firstvararg"
|
|
Marks a function as taking syslog-like arguments.
|
|
Allows use of the %m formatting code.
|
|
.Fa fmtarg
|
|
is the index of the format string in the argument list, and
|
|
.Fa firstvararg
|
|
is the index of the first item of the vararg list, or
|
|
.Dv 0
|
|
if the argument is a
|
|
.Ft va_list .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr clang 1 ,
|
|
.Xr gcc 1 ,
|
|
.Xr __builtin_object_size 3 ,
|
|
.Xr cdefs 3 ,
|
|
.Xr c 7
|
|
.Sh 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.
|