[apple/libc.git] / sys / cache.3

.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).
Commit	Line	Data
224c7076 A	1	.Dd September 21, 2006
	2	.Dt CACHE 3
	3	.Os Darwin
	4	.Sh NAME
	5	.Nm sys_cache_control ,
	6	.Nm sys_icache_invalidate ,
	7	.Nm sys_dcache_flush
	8	.Nd cache control
	9	.Sh LIBRARY
	10	.Lb libc
	11	.Sh SYNOPSIS
	12	.In libkern/OSCacheControl.h
	13	.Ft int
	14	.Fn sys_cache_control "int function" "void *start" "size_t len"
	15	.Ft void
	16	.Fn sys_icache_invalidate "void *start" "size_t len"
	17	.Ft void
	18	.Fn sys_dcache_flush "void *start" "size_t len"
	19	.Sh DESCRIPTION
	20	.Pp
	21	These functions operate on every cache line containing one of the
	22	.Fa len
	23	bytes of memory pointed to by
	24	.Fa start .
	25	Normally the operations apply to every
	26	processor in the system, but the exact semantics of these
	27	operations is platform dependent. They should be used with caution.
	28	.Pp
	29	.Fn sys_cache_control
	30	performs the operation specified by
	31	.Fa function .
	32	Refer to the header file for a list of currently supported functions.
	33	.Pp
	34	.Fn sys_icache_invalidate
	35	prepares memory for execution, typically by invalidating the instruction
	36	cache for the indicated range. This should be called
	37	after writing machine instructions to memory, and before
	38	executing them. On IA32 processors this function is a NOP, because
	39	their instruction caches are coherent.
	40	.Pp
	41	.Fn sys_dcache_flush
	42	writes modified data cache lines to main memory,
	43	and then invalidates all lines in the range being operated on.
	44	It can be useful when dealing with cache incoherent
	45	devices or DMA.
	46	.Sh RETURN VALUES
	47	.Fn sys_cache_control
	48	returns zero on success, ENOTSUP if
	49	.Fa function
	50	is not valid.
	51	.Sh SEE ALSO
	52	.Xr atomic 3 ,
	53	.Xr barrier 3
	54	.Sh HISTORY
	55	These functions first appeared in Mac OS 10.5 (Leopard).