cachelib.html

vxworks相关论文

will get one (line 11) from <b><i><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a></i>(&nbsp;)</b>.  A <b>CACHE_FUNCS</b> structure
(see <b>cacheLib.h</b>) is used to create a buffer that will not suffer from cache
coherency problems.  If the memory allocator fails (line 13), the driver
will typically return ERROR (line 14) and quit.
<p>
The driver fills the output buffer with initialization information,
device commands, and data (line 17), and is prepared to pass the
buffer to the device.  Before doing so, the driver must flush the data
cache (line 19) to ensure that the buffer is in memory, not hidden in
the cache.  The routine <b><i>drvWrite</i>(&nbsp;)</b> lets the device know that the data
is ready and where in memory it is located (line 20).
<p>
More driver code is executed (line 22), and the driver is then ready to
receive data that the device has placed in the buffer in memory (line
24).  Before the driver cache can work with the incoming data, it must
invalidate the data cache entries (line 25) 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 27), which the driver 
retrieves from memory.  Remember to free the buffer (line 29) acquired 
from the memory allocator.  The driver will return OK (line 30) to 
distinguish a successful from an unsuccessful operation.
<pre>STATUS drvExample2 (pBuf)       /* simple driver - great performance */
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);
    }
</pre>

Do not use <b>CACHE_DMA_FLUSH</b> or <b>CACHE_DMA_INVALIDATE</b> without first calling
<b><i><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a></i>(&nbsp;)</b>, 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 <b><i><a href="./cacheLib.html#cacheFlush">cacheFlush</a></i>(&nbsp;)</b> and
<b><i><a href="./cacheLib.html#cacheInvalidate">cacheInvalidate</a></i>(&nbsp;)</b> functions can be used at any time throughout the system
since they are affiliated with the hardware, not the malloc/free buffer.
<p>
A call to <b><i><a href="./cacheLib.html#cacheLibInit">cacheLibInit</a></i>(&nbsp;)</b> 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.
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 <b>a priori</b> 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 <b><i><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a></i>(&nbsp;)</b> might differ from 
the physical address seen by the device.  It uses the <b>CACHE_DMA_VIRT_TO_PHYS</b> 
and <b>CACHE_DMA_PHYS_TO_VIRT</b> macros in addition to the <b>CACHE_DMA_FLUSH</b> and
<b>CACHE_DMA_INVALIDATE</b> macros.
<p>
The <b><i><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a></i>(&nbsp;)</b> 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 <b><i>drvWrite</i>(&nbsp;)</b> routine
lets the device know that the data is ready and where in memory it is
located (line 11).  Note that the <b>CACHE_DMA_VIRT_TO_PHYS</b> macro converts
the buffer's virtual address to the corresponding physical address for the
device.
<p>
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 <b>CACHE_DMA_PHYS_TO_VIRT</b> 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.
<pre>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);
    }
</pre>
Driver Summary
The virtual-to-physical and physical-to-virtual function pointers
associated with <b><i><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a></i>(&nbsp;)</b> 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.
<p>
When <b><i><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a></i>(&nbsp;)</b> 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 <b><i><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a></i>(&nbsp;)</b> is the same
as the physical address, the function pointers are made NULL so that no calls
are made when the macros are expanded.
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 <b>sysCacheLibInit</b> is
set to <b><i>cacheXxxLibInit</i>(&nbsp;)</b> ("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 <b>cacheXxxLib</b> being linked in by <b>sysLib.c</b>.
For systems without caches and for those architectures with only one cache
design, there is no need for the <b>sysCacheLibInit</b> variable.
<pre>     FUNCPTR sysCacheLibInit = (FUNCPTR) cacheXxxLibInit;
</pre>
For cache systems with bus snooping, the flush and invalidate macros
should be NULLified to enhance system and driver performance in <b><i><a href="./sysLib.html#sysHwInit">sysHwInit</a></i>(&nbsp;)</b>.
<pre>     void sysHwInit ()
        {
        ...
        cacheLib.flushRtn = NULL;       /* no flush necessary */
        cacheLib.invalidateRtn = NULL;  /* no invalidate necessary */
        ...
        }
</pre>
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 <b><i><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a></i>(&nbsp;)</b> 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.
<p>
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 <b>CACHE_PIPE_FLUSH</b> macro.  External write buffers
may still need to be handled in a board-specific manner.
<p>
</blockquote><h4>INCLUDE FILES</h4><blockquote><p>
<b>cacheLib.h</b>
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./cacheLib.html#top">cacheLib</a></b>, Architecture-specific cache-management libraries (<b>cacheXxxLib</b>), <b><a href="./vmLib.html#top">vmLib</a></b>,  
<i>VxWorks Programmer's Guide: I/O System</i>

<hr>
<a name="cacheLibInit"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>cacheLibInit</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>cacheLibInit</i>(&nbsp;)</strong> - initialize the cache library for a processor architecture</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS cacheLibInit
    (
    CACHE_MODE instMode, /* inst cache mode */
    CACHE_MODE dataMode  /* data cache mode */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
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 
<b>sysCacheLibInit</b>.  Systems without cache coherency problems (i.e., bus 
snooping) should NULLify the flush and invalidate function pointers in 
the <b><a href="./cacheLib.html#top">cacheLib</a></b> structure to enhance driver and overall system performance.
This can be done in <b><i><a href="./sysLib.html#sysHwInit">sysHwInit</a></i>(&nbsp;)</b>.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, or ERROR if there is no cache library installed.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./cacheLib.html#top">cacheLib</a></b>

<hr>
<a name="cacheEnable"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>cacheEnable</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>cacheEnable</i>(&nbsp;)</strong> - enable the specified cache</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS cacheEnable
    (
    CACHE_TYPE cache /* cache to enable */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine invalidates the cache tags and enables the instruction or 
data cache.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, or ERROR if the cache type is invalid or the cache control
is not supported.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./cacheLib.html#top">cacheLib</a></b>

<hr>
<a name="cacheDisable"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>cacheDisable</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>cacheDisable</i>(&nbsp;)</strong> - disable the specified cache</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS cacheDisable
    (
    CACHE_TYPE cache /* cache to disable */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine flushes the cache and disables the instruction or data cache.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, or ERROR if the cache type is invalid or the cache control
is not supported.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./cacheLib.html#top">cacheLib</a></b>

<hr>
<a name="cacheLock"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>cacheLock</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>cacheLock</i>(&nbsp;)</strong> - lock all or part of a specified cache</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS cacheLock
    (
    CACHE_TYPE cache,   /* cache to lock */
    void *     address, /* virtual address */
    size_t     bytes    /* number of bytes to lock */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
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.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, or ERROR if the cache type is invalid or the cache control
is not supported.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./cacheLib.html#top">cacheLib</a></b>

<hr>
<a name="cacheUnlock"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>cacheUnlock</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>cacheUnlock</i>(&nbsp;)</strong> - unlock all or part of a specified cache</p>