.\" $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.