.Dd September 21, 2006
.Dt CACHE 3
.Os Darwin
.Sh NAME
.Nm sys_cache_control ,
.Nm sys_icache_invalidate ,
.Nm sys_dcache_flush
.Nd cache control
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In libkern/OSCacheControl.h
.Ft int
.Fn sys_cache_control "int function" "void *start" "size_t len"
.Ft void
.Fn sys_icache_invalidate "void *start" "size_t len"
.Ft void
.Fn sys_dcache_flush "void *start" "size_t len"
.Sh DESCRIPTION
.Pp
These functions operate on every cache line containing one of the 
.Fa len
bytes of memory pointed to by
.Fa start .
Normally the operations apply to every
processor in the system, but the exact semantics of these
operations is platform dependent.  They should be used with caution.
.Pp
.Fn sys_cache_control
performs the operation specified by
.Fa function .
Refer to the header file for a list of currently supported functions.
.Pp
.Fn sys_icache_invalidate
prepares memory for execution, typically by invalidating the instruction
cache for the indicated range.  This should be called
after writing machine instructions to memory, and before
executing them.  On IA32 processors this function is a NOP, because
their instruction caches are coherent.
.Pp
.Fn sys_dcache_flush
writes modified data cache lines to main memory,
and then invalidates all lines in the range being operated on.
It can be useful when dealing with cache incoherent
devices or DMA.
.Sh RETURN VALUES
.Fn sys_cache_control
returns zero on success, ENOTSUP if
.Fa function
is not valid.
.Sh SEE ALSO
.Xr atomic 3 ,
.Xr barrier 3
.Sh HISTORY
These functions first appeared in Mac OS 10.5 (Leopard).