📄 cachelib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/cacheLib.html - generated by refgen from cacheLib.c --> <title> cacheLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.htm"><i>VxWorks API Reference : OS Libraries</i></a></p></blockquote><h1>cacheLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>cacheLib</strong> - cache management library </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><a href="./cacheLib.html#cacheLibInit">cacheLibInit</a>( )</b> - initialize the cache library for a processor architecture<br><b><a href="./cacheLib.html#cacheEnable">cacheEnable</a>( )</b> - enable the specified cache<br><b><a href="./cacheLib.html#cacheDisable">cacheDisable</a>( )</b> - disable the specified cache<br><b><a href="./cacheLib.html#cacheLock">cacheLock</a>( )</b> - lock all or part of a specified cache<br><b><a href="./cacheLib.html#cacheUnlock">cacheUnlock</a>( )</b> - unlock all or part of a specified cache<br><b><a href="./cacheLib.html#cacheFlush">cacheFlush</a>( )</b> - flush all or some of a specified cache<br><b><a href="./cacheLib.html#cacheInvalidate">cacheInvalidate</a>( )</b> - invalidate all or some of a specified cache<br><b><a href="./cacheLib.html#cacheClear">cacheClear</a>( )</b> - clear all or some entries from a cache<br><b><a href="./cacheLib.html#cachePipeFlush">cachePipeFlush</a>( )</b> - flush processor write buffers to memory<br><b><a href="./cacheLib.html#cacheTextUpdate">cacheTextUpdate</a>( )</b> - synchronize the instruction and data caches<br><b><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a>( )</b> - allocate a cache-safe buffer for DMA devices and drivers<br><b><a href="./cacheLib.html#cacheDmaFree">cacheDmaFree</a>( )</b> - free the buffer acquired with <b><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a>( )</b><br><b><a href="./cacheLib.html#cacheDrvFlush">cacheDrvFlush</a>( )</b> - flush the data cache for drivers<br><b><a href="./cacheLib.html#cacheDrvInvalidate">cacheDrvInvalidate</a>( )</b> - invalidate data cache for drivers<br><b><a href="./cacheLib.html#cacheDrvVirtToPhys">cacheDrvVirtToPhys</a>( )</b> - translate a virtual address for drivers<br><b><a href="./cacheLib.html#cacheDrvPhysToVirt">cacheDrvPhysToVirt</a>( )</b> - translate a physical address for drivers<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This library provides architecture-independent routines for managingthe instruction and data caches. Architecture-dependent routines aredocumented in the architecture-specific libraries. <p>The cache library is initialized by <b><a href="./cacheLib.html#cacheLibInit">cacheLibInit</a>( )</b> in <b><a href="./usrConfig.html#usrInit">usrInit</a>( )</b>. The<b><a href="./cacheLib.html#cacheLibInit">cacheLibInit</a>( )</b> routine typically calls an architecture-specificinitialization routine in one of the architecture-specific libraries. Theinitialization routine places the cache in a known and quiescent state,ready for use, but not yet enabled. Cache devices are enabled and disabledby calls to <b><a href="./cacheLib.html#cacheEnable">cacheEnable</a>( )</b> and <b><a href="./cacheLib.html#cacheDisable">cacheDisable</a>( )</b>, respectively. <p>The structure <b>CACHE_LIB</b> in <b>cacheLib.h</b> provides a function pointer thatallows for the installation of different cache implementations in anarchitecture-independent manner. If the processor family allows more thanone cache implementation, the board support package (BSP) must select theappropriate cache library using the function pointer <b>sysCacheLibInit</b>.The <b><a href="./cacheLib.html#cacheLibInit">cacheLibInit</a>( )</b> routine calls the initialization function attached to<b>sysCacheLibInit</b> to perform the actual <b>CACHE_LIB</b> function pointerinitialization (see <b>cacheLib.h</b>). Note that <b>sysCacheLibInit</b> must beinitialized when declared; it need not exist for architectures with asingle cache design. Systems without caches have all NULL pointers in the<b>CACHE_LIB</b> structure. For systems with bus snooping, NULLifying the flushand invalidate function pointers in <b><a href="./sysLib.html#sysHwInit">sysHwInit</a>( )</b> improves overall systemand driver performance.<p>Function pointers also provide a way to supplement the cache library orattach user-defined cache functions for managing secondary cache systems.<p>Parameters specified by <b><a href="./cacheLib.html#cacheLibInit">cacheLibInit</a>( )</b> are used to select the cache mode,either write-through (<b>CACHE_WRITETHROUGH</b>) or copyback (<b>CACHE_COPYBACK</b>), aswell as to implement all other cache configuration features via softwarebit-flags. Note that combinations, such as setting copyback andwrite-through at the same time, do not make sense.<p>Typically, the first argument passed to cache routines after initialization is the <b>CACHE_TYPE</b>, which selects the data cache (<b>DATA_CACHE</b>) or the instruction cache (<b>INSTRUCTION_CACHE</b>). <p>Several routines accept two additional arguments: an address andthe number of bytes. Some cache operations can be applied to theentire cache (bytes = <b>ENTIRE_CACHE</b>) or to a portion of the cache. Thisrange specification allows the cache to be selectively locked, unlocked,flushed, invalidated, and cleared. The two complementary routines,<b><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a>( )</b> and <b><a href="./cacheLib.html#cacheDmaFree">cacheDmaFree</a>( )</b>, are tailored for efficient driver writing.The <b><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a>( )</b> routine attempts to return a "cache-safe" buffer,which is created by the MMU and a set of flush and invalidate functionpointers. Examples are provided below in the section "Using the CacheLibrary."<p>Most routines in this library return a STATUS value of OK, or ERROR if the cache selection is invalid or the cache operation fails. <p></blockquote><h4>BACKGROUND</h4><blockquote><p>The emergence of RISC processors and effective CISC caches has made cacheand MMU support a key enhancement to VxWorks. (For more information about MMUsupport, see the manual entry for <b><a href="./vmLib.html#top">vmLib</a></b>.) The VxWorks cache strategyis to maintain coherency between the data cache and RAM and between theinstruction and data caches. VxWorks also preserves overall systemperformance. The product is designed to support several architectures andboard designs, to have a high-performance implementation for drivers, andto make routines functional for users, as well as within the entireoperating system. The lack of a consistent cache design, even withinarchitectures, has required designing for the case with the greatest number ofcoherency issues (Harvard architecture, copyback mode, DMA devices,multiple bus masters, and no hardware coherency support).<p>Caches run in two basic modes, write-through and copyback. Thewrite-through mode forces all writes to the cache and to RAM, providingpartial coherency. Writing to RAM every time, however, slows down theprocessor and uses bus bandwidth. The copyback mode conserves processorperformance time and bus bandwidth by writing only to the cache, not RAM.Copyback cache entries are only written to memory on demand. A LeastRecently Used (LRU) algorithm is typically used to determine which cacheline to displace and flush. Copyback provides higher system performance,but requires more coherency support. Below is a logical diagram of acached system to aid in the visualization of the coherency issues.<pre> +---------------+ +-----------------+ +--------------+ | | | | | | | INSTRUCTION |---->| PROCESSOR |<--->| DATA CACHE | (3) | CACHE | | | | (copyback) | | | | | | | +---------------+ +-----------------+ +--------------+ ^ (2) ^ | | | +-----------------+ | | | | (1) | +-------------| RAM |<------------+ | | +-----------------+ ^ ^ | | +-------------+ | | +-------------+ | | | | | | | DMA Devices |<--+ +-->| VMEbus, etc.| | | | | +-------------+ +-------------+</pre>The loss of cache coherency for a VxWorks system occurs in three places:<p> (1) data cache / RAM<br> (2) instruction cache / data cache<br> (3) shared cache lines<p>A problem between the data cache and RAM (1) results from asynchronousaccesses (reads and writes) to the RAM by the processor and othermasters. Accesses by DMA devices and alternate bus masters (sharedmemory) are the primary causes of incoherency, which can be remedied withminor code additions to the drivers. <p>The instruction cache and data cache (2) can get out of sync when theloader, the debugger, and the interrupt connection routines are beingused. The instructions resulting from these operations are loaded intothe data cache, but not necessarily the instruction cache, in which casethere is a coherency problem. This can be fixed by "flushing" the datacache entries to RAM, then "invalidating" the instruction cache entries.The invalid instruction cache tags will force the retrieval of the newinstructions that the data cache has just flushed to RAM.<p>Cache lines that are shared (3) by more than one task create coherencyproblems. These are manifest when one thread of execution invalidates acache line in which entries may belong to another thread. This can beavoided by allocating memory on a cache line boundary, then rounding up toa multiple of the cache line size.<p>The best way to preserve cache coherency with optimal performance(Harvard architecture, copyback mode, no software intervention) isto use hardware with bus snooping capabilities. The caches, the RAM, theDMA devices, and all other bus masters are tied to a physical buswhere the caches can "snoop" or watch the bus transactions. Theaddress cycle and control (read/write) bits are broadcast on the busto allow snooping. Data transfer cycles are deferred until absolutelynecessary. When one of the entries on the physical side of the cacheis modified by an asynchronous action, the cache(s) marks itsentry(s) as invalid. If an access is made by the processor (logicalside) to the now invalid cached entry, it is forced to retrieve thevalid entry from RAM. If while in copyback mode the processor writesto a cached entry, the RAM version becomes stale. If another masterattempts to access that stale entry in RAM, the cache with the validversion pre-empts the access and writes the valid data to RAM. Theinterrupted access then restarts and retrieves the now-valid data inRAM. Note that this configuration allows only one valid entry at anytime. At this time, only a few boards provide the snooping capability; therefore, cache support software must be designed to handleincoherency hazards without degrading performance.<p>The determinism, interrupt latency, and benchmarks for a cached system areexceedingly difficult to specify (best case, worst case, average case) dueto cache hits and misses, line flushes and fills, atomic burst cycles,global and local instruction and data cache locking, copyback versuswrite-through modes, hardware coherency support (or lack of), and MMUoperations (table walks, TLB locking).<p></blockquote><h4>USING THE CACHE LIBRARY</h4><blockquote><p>The coherency problems described above can be overcome by adding cachesupport to existing software. For code segments that are nottime-critical (loader, debugger, interrupt connection), the followingsequence should be used first to flush the data cache entries and then to invalidate the corresponding instruction cache entries.<pre> cacheFlush (DATA_CACHE, address, bytes); cacheInvalidate (INSTRUCTION_CACHE, address, bytes);</pre>For time-critical code, implementation is up to the driver writer.The following are tips for using the VxWorks cache library effectively. <p>Incorporate cache calls in the driver program to maintain overall systemperformance. The cache may be disabled to facilitate driver development;however, high-performance production systems should operate with the cacheenabled. A disabled cache will dramatically reduce system performance fora completed application.<p>Buffers can be static or dynamic. Mark buffers "non-cacheable" to avoidcache coherency problems. This usually requires MMU support. Dynamicbuffers are typically smaller than their static counterparts, and they areallocated and freed often. When allocating either type of buffer, itshould be designated non-cacheable; however, dynamic buffers should bemarked "cacheable" before being freed. Otherwise, memory becomesfragmented with numerous non-cacheable dynamic buffers.<p>Alternatively, use the following flush/invalidate scheme to maintain cache coherency.<pre> cacheInvalidate (DATA_CACHE, address, bytes); /* input buffer */ cacheFlush (DATA_CACHE, address, bytes); /* output buffer */</pre>The principle is to flush output buffers before each use and invalidateinput buffers before each use. Flushing only writes modified entries backto RAM, and instruction cache entries never get modified.<p>Several flush and invalidate macros are defined in <b>cacheLib.h</b>. Sinceoptimized code uses these macros, they provide a mechanism to avoidunnecessary cache calls and accomplish the necessary work (return OK).Needless work includes flushing a write-through cache, flushing orinvalidating cache entries in a system with bus snooping, and flushingor invalidating cache entries in a system without caches. The macrosare set to reflect the state of the cache system hardware and software.Example 1The following example is of a simple driver that uses <b><a href="./cacheLib.html#cacheFlush">cacheFlush</a>( )</b>and <b><a href="./cacheLib.html#cacheInvalidate">cacheInvalidate</a>( )</b> from the cache library to maintain coherency andperformance. There are two buffers (lines 3 and 4), one for input andone for output. The output buffer is obtained by the call to<b><a href="./memLib.html#memalign">memalign</a>( )</b>, a special version of the well-known <b><a href="./memPartLib.html#malloc">malloc</a>( )</b> routine (line6). It returns a pointer that is rounded down and up to the alignmentparameter's specification. Note that cache lines should not be shared,therefore <b>_CACHE_ALIGN_SIZE</b> is used to force alignment. If the memoryallocator fails (line 8), the driver will typically return ERROR (line9) and quit.<p>The driver fills the output buffer with initialization information,device commands, and data (line 11), and is prepared to pass thebuffer to the device. Before doing so the driver must flush the datacache (line 13) to ensure that the buffer is in memory, not hidden inthe cache. The <b>drvWrite( )</b> routine lets the device know that the datais ready and where in memory it is located (line 14).<p>More driver code is executed (line 16), then the driver is ready toreceive data that the device has placed in an input buffer in memory(line 18). Before the driver can work with the incoming data, it mustinvalidate the data cache entries (line 19) that correspond to the inputbuffer's data in order to eliminate stale entries. That done, it is safe forthe driver to retrieve the input data from memory (line 21). Rememberto free (line 23) the buffer acquired from the memory allocator. Thedriver will return OK (line 24) to distinguish a successful from anunsuccessful operation.<pre>STATUS drvExample1 () /* simple driver - good performance */ {3: void * pInBuf; /* input buffer */4: void * pOutBuf; /* output buffer */ 6: pOutBuf = memalign (_CACHE_ALIGN_SIZE, BUF_SIZE);8: if (pOutBuf == NULL)9: return (ERROR); /* memory allocator failed */11: /* other driver initialization and buffer filling */13: cacheFlush (DATA_CACHE, pOutBuf, BUF_SIZE);14: drvWrite (pOutBuf); /* output data to device */16: /* more driver code */18: cacheClear (DATA_CACHE, pInBuf, BUF_SIZE);19: pInBuf = drvRead (); /* wait for device data */21: /* handle input data from device */23: free (pOutBuf); /* return buffer to memory pool */24: return (OK); }</pre>Extending this flush/invalidate concept further, individualbuffers can be treated this way, not just the entire cache system. The idea is to avoidunnecessary flush and/or invalidate operations on a per-buffer basis byallocating cache-safe buffers. Calls to <b><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a>( )</b> optimize theflush and invalidate function pointers to NULL, if possible, whilemaintaining data integrity.Example 2The following example is of a high-performance driver that takes advantageof the cache library to maintain coherency. It uses <b><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a>( )</b> andthe macros <b>CACHE_DMA_FLUSH</b> and <b>CACHE_DMA_INVALIDATE</b>. A buffer pointeris passed as a parameter (line 2). If the pointer is not NULL (line 7),it is assumed that the buffer will not experience any cache coherencyproblems. If the driver was not provided with a cache-safe buffer, itwill get one (line 11) from <b><a href="./cacheLib.html#cacheDmaMalloc">cacheDmaMalloc</a>( )</b>. A <b>CACHE_FUNCS</b> structure(see <b>cacheLib.h</b>) is used to create a buffer that will not suffer from cachecoherency problems. If the memory allocator fails (line 13), the driverwill typically return ERROR (line 14) and quit.⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -