cachelib.c

VxWorks操作系统内核源代码

2:  void *	pBuf;		/@ buffer pointer parameter @/

    {
5:  if (pBuf != NULL)
	{
7:	/@ no cache coherency problems with buffer passed to driver @/
	}
    else
        {
11:     pBuf = cacheDmaMalloc (BUF_SIZE);

13:     if (pBuf == NULL)
14:         return (ERROR);	/@ memory allocator failed @/
        }

17: /@ other driver initialization and buffer filling @/

19: CACHE_DMA_FLUSH (pBuf, BUF_SIZE);
20: drvWrite (pBuf);		/@ output data to device @/

22: /@ more driver code @/

24: drvWait ();			/@ wait for device data @/
25: CACHE_DMA_INVALIDATE (pBuf, BUF_SIZE);

27: /@ handle input data from device @/

29: cacheDmaFree (pBuf);	/@ return buffer to memory pool @/
30: return (OK);
    }
.CE

Do not use CACHE_DMA_FLUSH or CACHE_DMA_INVALIDATE without first calling
cacheDmaMalloc(), otherwise the function pointers may not be
initialized correctly.  Note that this driver scheme assumes all cache
coherency modes have been set before driver initialization, and that
the modes do not change after driver initialization.  The cacheFlush() and
cacheInvalidate() functions can be used at any time throughout the system
since they are affiliated with the hardware, not the malloc/free buffer.

A call to cacheLibInit() in write-through mode makes the flush function
pointers NULL.  Setting the caches in copyback mode (if supported) should
set the pointer to and call an architecture-specific flush routine.  The
invalidate and flush macros may be NULLified if the hardware provides bus
snooping and there are no cache coherency problems.
.SH "Example 3"
The next example shows a more complex driver that requires address
translations to assist in the cache coherency scheme.  The previous
example had `a priori' knowledge of the system memory map and/or the device
interaction with the memory system.  This next driver demonstrates a case 
in which the virtual address returned by cacheDmaMalloc() might differ from 
the physical address seen by the device.  It uses the CACHE_DMA_VIRT_TO_PHYS 
and CACHE_DMA_PHYS_TO_VIRT macros in addition to the CACHE_DMA_FLUSH and
CACHE_DMA_INVALIDATE macros.

The cacheDmaMalloc() routine initializes the buffer pointer (line 3).  If
the memory allocator fails (line 5), the driver will typically return
ERROR (line 6) and quit.  The driver fills the output buffer with
initialization information, device commands, and data (line 8), and is
prepared to pass the buffer to the device.  Before doing so, the driver
must flush the data cache (line 10) to ensure that the buffer is in
memory, not hidden in the cache.  The flush is based on the virtual
address since the processor filled in the buffer.  The drvWrite() routine
lets the device know that the data is ready and where in memory it is
located (line 11).  Note that the CACHE_DMA_VIRT_TO_PHYS macro converts
the buffer's virtual address to the corresponding physical address for the
device.

More driver code is executed (line 13), and the driver is then ready to
receive data that the device has placed in the buffer in memory (line
15).  Note the use of the CACHE_DMA_PHYS_TO_VIRT macro on the buffer
pointer received from the device.  Before the driver cache can work
with the incoming data, it must invalidate the data cache entries (line
16) that correspond to the input buffer's data in order to eliminate 
stale entries.  That done, it is safe for the driver to handle the input 
data (line 17), which it retrieves from memory.  Remember to free (line
19) the buffer acquired from the memory allocator.  The driver will return
OK (line 20) to distinguish a successful from an unsuccessful operation.
.CS
STATUS drvExample3 ()           /@ complex driver - great performance @/ {
3:  void * pBuf = cacheDmaMalloc (BUF_SIZE);

5:  if (pBuf == NULL)
6:      return (ERROR);		/@ memory allocator failed @/

8: /@ other driver initialization and buffer filling @/

10: CACHE_DMA_FLUSH (pBuf, BUF_SIZE);
11: drvWrite (CACHE_DMA_VIRT_TO_PHYS (pBuf));

13: /@ more driver code @/

15: pBuf = CACHE_DMA_PHYS_TO_VIRT (drvRead ());
16: CACHE_DMA_INVALIDATE (pBuf, BUF_SIZE);

17: /@ handle input data from device @/

19: cacheDmaFree (pBuf);	/@ return buffer to memory pool @/
20: return (OK);
    }
.CE
.SH "Driver Summary"
The virtual-to-physical and physical-to-virtual function pointers
associated with cacheDmaMalloc() are supplements to a cache-safe buffer.
Since the processor operates on virtual addresses and the devices access
physical addresses, discrepant addresses can occur and might prevent
DMA-type devices from being able to access the allocated buffer.
Typically, the MMU is used to return a buffer that has pages marked as 
non-cacheable.  An MMU is used to translate virtual addresses into physical
addresses, but it is not guaranteed that this will be a "transparent"
translation.

When cacheDmaMalloc() does something that makes the virtual address
different from the physical address needed by the device, it provides the
translation procedures.  This is often the case when using translation
lookaside buffers (TLB) or a segmented address space to inhibit caching
(e.g., by creating a different virtual address for the same physical
space.)  If the virtual address returned by cacheDmaMalloc() is the same
as the physical address, the function pointers are made NULL so that no calls
are made when the macros are expanded.
.SH "Board Support Packages"
Each board for an architecture with more than one cache implementation has
the potential for a different cache system.  Hence the BSP for selecting
the appropriate cache library.  The function pointer `sysCacheLibInit' is
set to cacheXxxLibInit() ("Xxx" refers to the chip-specific name of a
library or function) so that the function pointers for that cache system
will be initialized and the linker will pull in only the desired cache
library.  Below is an example of cacheXxxLib being linked in by sysLib.c.
For systems without caches and for those architectures with only one cache
design, there is no need for the `sysCacheLibInit' variable.
.CS
     FUNCPTR sysCacheLibInit = (FUNCPTR) cacheXxxLibInit;
.CE
For cache systems with bus snooping, the flush and invalidate macros
should be NULLified to enhance system and driver performance in sysHwInit().
.CS
     void sysHwInit ()
        {
        ...
	cacheLib.flushRtn = NULL;	/@ no flush necessary @/
	cacheLib.invalidateRtn = NULL;	/@ no invalidate necessary @/
        ...
        }
.CE
There may be some drivers that require numerous cache calls, so many 
that they interfere with the code clarity.  Additional checking can be
done at the initialization stage to determine if cacheDmaMalloc() returned
a buffer in non-cacheable space.  Remember that it will return a
cache-safe buffer by virtue of the function pointers.  Ideally, these are
NULL, since the MMU was used to mark the pages as non-cacheable.  The
macros CACHE_Xxx_IS_WRITE_COHERENT and CACHE_Xxx_IS_READ_COHERENT
can be used to check the flush and invalidate function pointers,
respectively.

Write buffers are used to allow the processor to continue execution while
the bus interface unit moves the data to the external device.  In theory,
the write buffer should be smart enough to flush itself when there is a
write to non-cacheable space or a read of an item that is in the buffer.
In those cases where the hardware does not support this, the software must
flush the buffer manually.  This often is accomplished by a read to
non-cacheable space or a NOP instruction that serializes the chip's
pipelines and buffers.  This is not really a caching issue; however, the
cache library provides a CACHE_PIPE_FLUSH macro.  External write buffers
may still need to be handled in a board-specific manner.

INTERNAL 
The manipulation of the cache and/or cache registers should be done in
the most efficient way possible to maintain driver performance.  Some
of the code may have to be written in assembly language depending on
the cache design.  Allowing different granularities for the cache
operations helps reduce the overhead associated with the cache
coherency software.  This may be applicable to all the cache calls,
and will vary with each architecture.  Examples are entry, line, set,
page, segment, region, context.  MMU support is needed to selectively
enable and disable parts of the address space, and is typically done
on a "page" basis.  Board-specific and some secondary cache operations
should be part of the BSP.  The inclusion of routines that assist in
debugging (cache tag dumps) is desirable.

The memory allocator must round addresses down to a cache line
boundary, and return a number of bytes that is a multiple of the cache
line size to prevent shared cache lines.  Cache operations on address
ranges must be rounded down and up to the appropriate boundaries
(line, page, etc.).  _CACHE_ALIGN_SIZE may be used to force alignment
when using memalign().

The atomicity of the cache operations is preserved by locking
interrupts and disabling caching.  Interrupts should be locked out
while the cache is disabled since interrupt handling and other tasks
would be run with caching disabled until the preempted task is
switched back in, if it is ever switched back in.  The cache must be
disabled while performing most of these operations.  For example, the
cache should not be loading new entries during an invalidate operation
and lose critical data such as stack entries.

cacheDmaMalloc() returns the memalign() return value, or NULL if there
is some procedure-specific error in cache<Xxx>DmaMalloc().  The flush
and invalidate function pointers should be set as follows:

    NO DATA CACHE		cacheDrv.flushRtn = NULL
                                cacheDrv.invalidateRtn = NULL
    DATA CACHE DISABLED		cacheDrv.flushRtn = NULL
                                cacheDrv.invalidateRtn = NULL
    DATA CACHING INHIBITED	cacheDrv.flushRtn = NULL
                                cacheDrv.invalidateRtn = NULL
    BUS SNOOPING HARDWARE	cacheDrv.flushRtn = NULL
                                cacheDrv.invalidateRtn = NULL
    WRITE-THROUGH DATA CACHE	cacheDrv.flushRtn = NULL
                                cacheDrv.invalidate = cache<Xxx>Invalidate()
    COPYBACK DATA CACHE		cacheDrv.flushRtn = cache<Xxx>Flush()
                                cacheDrv.invalidate = cache<Xxx>Invalidate()
    RETURN NULL BUFFER POINTER	cacheDrv.flushRtn = cache<Xxx>Flush()
                                cacheDrv.invalidate = cache<Xxx>Invalidate()

The setting of the flush function pointer may not be NULL if the system has 
write buffers that need to be flushed.

INCLUDE FILES: cacheLib.h

SEE ALSO: Architecture-specific cache-management libraries (cacheXxxLib), vmLib,
.pG "I/O System"
*/

#include "cacheLib.h"
#include "stdlib.h"
#include "private/vmLibP.h"

/* globals */

FUNCPTR cacheDmaMallocRtn = NULL;	/* malloc dma memory if MMU */
FUNCPTR cacheDmaFreeRtn = NULL;		/* free dma memory if MMU */

CACHE_MODE cacheDataMode = CACHE_DISABLED;	/* data cache mode */
BOOL cacheDataEnabled = FALSE;		/* data cache disabled */
BOOL cacheMmuAvailable = FALSE;		/* MMU support available */

/* externals */

IMPORT FUNCPTR sysCacheLibInit;		/* Board-specific cache library */

/**************************************************************************
*
* cacheLibInit - initialize the cache library for a processor architecture
*
* This routine initializes the function pointers for the appropriate cache 
* library.  For architectures with more than one cache implementation, the
* board support package must select the appropriate cache library with 
* `sysCacheLibInit'.  Systems without cache coherency problems (i.e., bus 
* snooping) should NULLify the flush and invalidate function pointers in 
* the cacheLib structure to enhance driver and overall system performance.
* This can be done in sysHwInit().
* 
* RETURNS: OK, or ERROR if there is no cache library installed.
*/

STATUS cacheLibInit
    (
    CACHE_MODE	instMode,		/* inst cache mode */
    CACHE_MODE	dataMode		/* data cache mode */
    )
    {
#if _ARCH_MULTIPLE_CACHELIB
    /* BSP selection of cache library */

    return ((STATUS) (sysCacheLibInit == NULL) ? ERROR :
	    (*sysCacheLibInit) (instMode, dataMode));
#else
    /* Single cache library for arch */

    return (cacheArchLibInit (instMode, dataMode));
#endif	/* _ARCH_MULTIPLE_CACHELIB */
    }

/**************************************************************************
*
* cacheEnable - enable the specified cache
*
* This routine invalidates the cache tags and enables the instruction or 
* data cache.
*
* RETURNS: OK, or ERROR if the cache type is invalid or the cache control
* is not supported.
*/

STATUS cacheEnable
    (
    CACHE_TYPE	cache		/* cache to enable */
    )
    {
    return ((cacheLib.enableRtn == NULL) ? ERROR : 
            (cacheLib.enableRtn) (cache));
    }

/**************************************************************************
*
* cacheDisable - disable the specified cache
*
* This routine flushes the cache and disables the instruction or data cache.
*
* RETURNS: OK, or ERROR if the cache type is invalid or the cache control
* is not supported.
*/

STATUS cacheDisable
    (
    CACHE_TYPE	cache		/* cache to disable */
    )
    {
    return ((cacheLib.disableRtn == NULL) ? ERROR : 
            (cacheLib.disableRtn) (cache));
    }

/**************************************************************************
*
* cacheLock - lock all or part of a specified cache
*
* This routine locks all (global) or some (local) entries in the specified 
* cache.  Cache locking is useful in real-time systems.  Not all caches can 
* perform locking.
*
* RETURNS: OK, or ERROR if the cache type is invalid or the cache control
* is not supported.
*/

STATUS cacheLock
    (