NAME

cachectl() − flush and/or purge the cache

SYNOPSIS

#include <sys/cache.h>

int cachectl(int cachecmd, void *address, size_t length);

DESCRIPTION

cachectl() permits a program to flush or purge data in the data and/or instruction caches.  The features provided by cachectl() are not needed by most programs.  It is primarily used for programs that do dynamic loading or contain self-modifying code.  Programs that do dynamic loading or contain self-modifying code can use the CC_IPURGE request, after the new code has been written to memory, to ensure that the correct code will be fetched by the instruction cache during execution.  The CC_FLUSH, CC_PURGE, and CC_EXTPURGE requests should only be used by applications that are highly hardware dependent and which have detailed knowledge of hardware internals. 

The cachecmd parameter specifies what operations to carry out on the cache or chaches.  cachecmd should contain one of the following values, which are defined in <sys/cache.h>:

CC_PURGE Purge the cache.  Dirty cache entries are discarded without being written to memory.  A “dirty” cache entry is an entry that has been modified, but has not been written back to the corresponding memory location. 

CC_FLUSH Flush the cache.  Dirty cache entries are copied back to the corresponding memory locations.  This operation is the same as CC_PURGE on models that do not have a copyback cache. 

CC_IPURGE Flush any dirty data cache entries, then purge any instruction cache entries which are “stale”.  A “stale” instruction cache entry is an entry that is older than the corresponding memory location.  This can happen if the corresponding memory location was written to (via the data cache).  This operation is useful for self-modifying code. 

The following mask, defined in <sys/cache.h>, can be OR ed together with one of the above values in order to purge the external cache (if one exists) at the same time. 

CC_EXTPURGE Purge the external cache (if any). 

The address parameter specifies the start address of the area to be flushed and/or purged.  If the specified start address is a null pointer, the operation is applied to the entire cache or caches specified by the cachecmd parameter.  Selective flushing and/or purging is not supported on all models.  Some models have restrictions on the legal values for the address parameter.  See DEPENDENCIES for details about specific hardware. 

The length parameter is used only when a start address is specified.  It controls the length of the area to be flushed or purged. 

EXAMPLES

The following call to cachectl() requests that the entire data cache be flushed, followed by a purge of the instruction cache. 

cachectl (CC_IPURGE, 0, 0);

RETURN VALUE

cachectl() returns 0 if the operation succeeds.  Otherwise it returns −1.  The semantics of cachectl(), when the address parameter contains a bad address, is subject to change and may vary from machine to machine. 

ERRORS

cachectl() fails and sets errno to the value indicated if:

[EINVAL] cachecmd is not a a valid request. 

DEPENDENCIES

Series 300/400

The MC68020 and MC68030 processors do not have a copyback cache.  Selective purging is not supported for the MC68020 and MC68030 processors.  Selective purging and flushing is supported on the MC68040 processor, but only under the following conditions:

• If the length parameter is 16, the cache line which includes address is flushed and/or purged (i.e., the 4 least significant bits of the address are ignored). 

• If the length parameter is 4096, the page which includes address is flushed and/or purged (i.e., the 12 least significant bits of the address are ignored).  If the length parameter is not 16 or 4096, the operation is applied to the entire cache or caches specified by the cachecmd parameter. 

On the MC68040 microprocessor, CC_PURGE instead performs a CC_FLUSH if the length parameter is not 16 or 4096. 

AUTHOR

cachectl() was developed by HP. 

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992