116 lines
3.5 KiB
Groff
116 lines
3.5 KiB
Groff
.\" $NetBSD: __builtin_prefetch.3,v 1.3 2010/12/22 22:02:54 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" 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 December 22, 2010
|
|
.Dt __BUILTIN_PREFETCH 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm __builtin_prefetch
|
|
.Nd GNU extension to prefetch memory
|
|
.Sh SYNOPSIS
|
|
.Ft void
|
|
.Fn __builtin_prefetch "const void *addr" "..."
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn __builtin_prefetch
|
|
function prefetches memory from
|
|
.Fa addr .
|
|
The rationale is to minimize cache-miss latency by
|
|
trying to move data into a cache before accessing the data.
|
|
Possible use cases include frequently called sections of code
|
|
in which it is known that the data in a given address is likely
|
|
to be accessed soon.
|
|
.Pp
|
|
In addition to
|
|
.Fa addr ,
|
|
there are two optional
|
|
.Xr stdarg 3
|
|
arguments,
|
|
.Fa rw
|
|
and
|
|
.Fa locality .
|
|
The value of the latter should be a compile-time
|
|
constant integer between 0 and 3.
|
|
The higher the value, the higher the temporal locality in the data.
|
|
When
|
|
.Fa locality
|
|
is 0, it is assumed that there is little or no temporal locality in the data;
|
|
after access, it is not necessary to leave the data in the cache.
|
|
The default value is 3.
|
|
The value of
|
|
.Fa rw
|
|
is either 0 or 1, corresponding with read and write prefetch, respectively.
|
|
The default value of
|
|
.Fa rw
|
|
is 0.
|
|
Also
|
|
.Fa rw
|
|
must be a compile-time constant integer.
|
|
.Pp
|
|
The
|
|
.Fn __builtin_prefetch
|
|
function translates into prefetch instructions
|
|
only if the architecture has support for these.
|
|
If there is no support,
|
|
.Fa addr
|
|
is evaluated only if it includes side effects,
|
|
although no warnings are issued by
|
|
.Xr gcc 1 .
|
|
.Sh EXAMPLES
|
|
The following optimization appears in the heavily used
|
|
.Fn cpu_in_cksum
|
|
function that calculates checksums for the
|
|
.Xr inet 4
|
|
headers:
|
|
.Bd -literal -offset indent
|
|
while (mlen >= 32) {
|
|
__builtin_prefetch(data + 32);
|
|
partial += *(uint16_t *)data;
|
|
partial += *(uint16_t *)(data + 2);
|
|
partial += *(uint16_t *)(data + 4);
|
|
|
|
\&...
|
|
|
|
partial += *(uint16_t *)(data + 28);
|
|
partial += *(uint16_t *)(data + 30);
|
|
|
|
data += 32;
|
|
mlen -= 32;
|
|
|
|
\&...
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr gcc 1 ,
|
|
.Xr attribute 3
|
|
.Rs
|
|
.%A Ulrich Drepper
|
|
.%T What Every Programmer Should Know About Memory
|
|
.%D November 21, 2007
|
|
.%U http://www.akkadia.org/drepper/cpumemory.pdf
|
|
.Re
|
|
.Sh CAVEATS
|
|
This is a non-standard, compiler-specific extension.
|