1.\" $NetBSD: attribute.3,v 1.16 2014/04/21 15:52:27 riastradh Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jukka Ruohonen. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 25, 2013 31.Dt ATTRIBUTE 3 32.Os 33.Sh NAME 34.Nm attribute 35.Nd non-standard compiler attribute extensions 36.Sh SYNOPSIS 37.In sys/cdefs.h 38.Pp 39.Ic __dead 40.Pp 41.Ic __pure 42.Pp 43.Ic __constfunc 44.Pp 45.Ic __noinline 46.Pp 47.Ic __unused 48.Pp 49.Ic __used 50.Pp 51.Ic __diagused 52.Pp 53.Ic __debugused 54.Pp 55.Ic __packed 56.Pp 57.Fn __aligned "x" 58.Fn __section "section" 59.Pp 60.Ic __read_mostly 61.Pp 62.Ic __cacheline_aligned 63.Pp 64.Fn __predict_true "exp" 65.Pp 66.Fn __predict_false "exp" 67.Sh DESCRIPTION 68As an extension to the C standard, some compilers allow non-standard 69attributes to be associated with functions, variables, or types, to 70modify some aspect of the way the compiler treats the associated item. 71The 72.Tn GNU 73Compiler Collection 74.Pq Tn GCC , 75and 76.Tn LLVM/Clang , 77use the 78.Em __attribute__ 79syntax for such attributes, 80but different versions of the compilers support different attributes, 81and other compilers may use entirely different syntax. 82.Pp 83.Nx 84code should usually avoid direct use of the 85.Em __attribute__ 86or similar syntax provided by specific compilers. 87Instead, 88.Nx Ap s 89.In sys/cdefs.h 90header file 91provides several attribute macros in a namespace 92reserved for the implementation (beginning with 93.Ql __ ) , 94that expand to the appropriate syntax for the compiler that is in use. 95.Sh ATTRIBUTES 96.Bl -tag -width abc 97.It Ic __dead 98Certain functions, such as 99.Xr abort 3 100and 101.Xr exit 3 , 102can never return any value. 103When such a function is declared with 104.Ic __dead , 105certain optimizations are possible. 106Obviously a 107.Ic __dead 108function can never have return type other than 109.Vt void . 110.It Ic __pure 111A 112.Ic __pure 113function is defined to be one that has no effects except 114the return value, which is assumed to depend only on the 115function parameters and/or global variables. 116Any access to parameters and/or global variables must also be read-only. 117A function that depends on volatile memory, or other comparable 118system resource that can change between two consecutive calls, 119can never be 120.Ic __pure . 121Many 122.Xr math 3 123functions satisfy the definition of a 124.Ic __pure 125function, at least in theory. 126Other examples include 127.Xr strlen 3 128and 129.Xr strcmp 3 . 130.It Ic __constfunc 131A 132.Dq const function 133is a stricter variant of 134.Dq pure functions . 135In addition to the restrictions of pure functions, a function declared with 136.Ic __constfunc 137can never access global variables nor take pointers as parameters. 138The return value of these functions must depend 139only on the passed-by-value parameters. 140Note also that a function that calls non-const functions can not be 141.Ic __constfunc . 142The canonical example of a const function would be 143.Xr abs 3 . 144As with pure functions, 145certain micro-optimizations are possible for functions declared with 146.Ic __constfunc . 147.It Ic __noinline 148Sometimes it is known that inlining is undesirable or that 149a function will perform incorrectly when inlined. 150The 151.Ic __noinline 152macro expands to a function attribute that prevents 153the compiler from inlining the function, irrespective 154of whether the function was declared with the 155.Em inline 156keyword. 157The attribute takes precedence over all 158other compiler options related to inlining. 159.It Ic __unused 160Marking an unused function with the 161.Ic __unused 162macro inhibits warnings that a function is defined but not used. 163Marking a variable with the 164.Ic __unused 165macro inhibits warnings that the variable is unused, 166or that it is set but never read. 167.It Ic __used 168The 169.Ic __used 170macro expands to an attribute that informs the compiler 171that a static variable or function is to be always retained 172in the object file even if it is unreferenced. 173.It Ic __diagused 174The 175.Ic __diagused 176macro expands to an attribute that informs the compiler 177that a variable or function is used only in diagnostic code, 178and may be unused in non-diagnostic code. 179.Pp 180In the kernel, variables that are used when 181.Dv DIAGNOSTIC 182is defined, but unused when 183.Dv DIAGNOSTIC 184is not defined, may be declared with 185.Ic __diagused . 186In userland, variables that are used when 187.Dv NDEBUG 188is not defined, but unused when 189.Dv NDEBUG 190is defined, may be declared with 191.Ic __diagused . 192.Pp 193Variables used only in 194.Xr assert 3 195or 196.Xr KASSERT 9 197macros are likely candidates for being declared with 198.Ic __diagused . 199.It Ic __debugused 200The 201.Ic __debugused 202macro expands to an attribute that informs the compiler 203that a variable or function is used only in debug code, 204and may be unused in non-debug code. 205.Pp 206In either the kernel or userland, variables that are used when 207.Dv DEBUG 208is defined, but unused when 209.Dv DEBUG 210is not defined, may be declared with 211.Ic __debugused . 212.Pp 213In the kernel, variables used only in 214.Xr KDASSERT 9 215macros are likely candidates for being declared with 216.Ic __debugused . 217There is no established convention for the use of 218.Dv DEBUG 219in userland code. 220.It Ic __packed 221The 222.Ic __packed 223macro expands to an attribute that forces a variable or 224structure field to have the smallest possible alignment, 225potentially disregarding architecture specific alignment requirements. 226The smallest possible alignment is effectively one byte 227for variables and one bit for fields. 228If specified on a 229.Vt struct 230or 231.Vt union , 232all variables therein are also packed. 233The 234.Ic __packed 235macro is often useful when dealing with data that 236is in a particular static format on the disk, wire, or memory. 237.It Fn __aligned "x" 238The 239.Fn __aligned 240macro expands to an attribute that specifies the minimum alignment 241in bytes for a variable, structure field, or function. 242In other words, the specified object should have an alignment of at least 243.Fa x 244bytes, as opposed to the minimum alignment requirements dictated 245by the architecture and the 246.Tn ABI . 247Possible use cases include: 248.Bl -bullet -offset indent 249.It 250Mixing assembly and C code. 251.It 252Dealing with hardware that may impose alignment requirements 253greater than the architecture itself. 254.It 255Using instructions that may impose special alignment requirements. 256Typical example would be alignment of frequently used objects along 257processor cache lines. 258.El 259.Pp 260Note that when used with functions, structures, or structure members, 261.Fn __aligned 262can only be used to increase the alignment. 263If the macro is however used as part of a 264.Vt typedef , 265the alignment can both increase and decrease. 266Otherwise it is only possible to decrease the alignment 267for variables and fields by using the 268.Ic __packed 269macro. 270The effectiveness of 271.Fn __aligned 272is largely dependent on the linker. 273The 274.Xr __alignof__ 3 275operator can be used to examine the alignment. 276.It Fn __section "section" 277The 278.Fn __section 279macro expands to an attribute that specifies a particular 280.Fa section 281to which a variable or function should be placed. 282Normally the compiler places the generated objects to sections such as 283.Dq data 284or 285.Dq text . 286By using 287.Fn __section , 288it is possible to override this behavior, perhaps in order to place 289some variables into particular sections specific to unique hardware. 290.It Ic __read_mostly 291The 292.Ic __read_mostly 293macro uses 294.Fn __section 295to place a variable or function into the 296.Dq .data.read_mostly 297section of the (kernel) 298.Xr elf 5 . 299The use of 300.Ic __read_mostly 301allows infrequently modified data to be grouped together; 302it is expected that the cachelines of rarely and frequently modified 303data structures are this way separated. 304Candidates for 305.Ic __read_mostly 306include variables that are initialized once, 307read very often, and seldom written to. 308.It Ic __cacheline_aligned 309The 310.Ic __cacheline_aligned 311macro behaves like 312.Ic __read_mostly , 313but the used section is 314.Dq .data.cacheline_aligned 315instead. 316It also uses 317.Fn __aligned 318to set the minimum alignment into a predefined coherency unit. 319This should ensure that frequently used data structures are 320aligned on cacheline boundaries. 321Both 322.Ic __cacheline_aligned 323and 324.Ic __read_mostly 325are only available for the kernel. 326.It Ic __predict_true 327A branch is generally defined to be a conditional execution of a 328program depending on whether a certain flow control mechanism is altered. 329Typical example would be a 330.Dq if-then-else 331sequence used in high-level languages or 332a jump instruction used in machine-level code. 333A branch prediction would then be defined as an 334attempt to guess whether a conditional branch will be taken. 335.Pp 336The macros 337.Fn __predict_true 338and 339.Fn __predict_false 340annotate the likelihood of whether 341a branch will evaluate to true or false. 342The rationale is to improve instruction pipelining. 343Semantically 344.Ic __predict_true 345expects that the integral expression 346.Fa exp 347yields nonzero. 348.It Ic __predict_false 349The 350.Ic __predict_false 351expands to an attribute that instructs the compiler 352to predict that a given branch will be likely false. 353As programmers are notoriously bad at predicting 354the likely behavior of their code, profiling and 355empirical evidence should precede the use of 356.Ic __predict_false 357and 358.Ic __predict_true . 359.El 360.Sh SEE ALSO 361.Xr clang 1 , 362.Xr gcc 1 , 363.Xr __builtin_object_size 3 , 364.Xr cdefs 3 , 365.Xr c 7 366.Sh CAVEATS 367It goes without saying that portable applications 368should steer clear from non-standard extensions specific 369to any given compiler. 370Even when portability is not a concern, 371use these macros sparsely and wisely. 372