1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="HAL Interfaces"
23 HREF="hal-interfaces.html"><LINK
26 HREF="hal-input-and-output.html"><LINK
28 TITLE="Linker Scripts"
29 HREF="hal-linker-scripts.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="hal-input-and-output.html"
65 >Chapter 9. HAL Interfaces</TD
71 HREF="hal-linker-scripts.html"
85 NAME="HAL-CACHE-CONTROL">Cache Control</H1
87 >This section contains definitions for supporting control
88 of the caches on the CPU.</P
90 >These definitions are usually found in the header file
93 >cyg/hal/hal_cache.h</TT
94 >. This file may be defined in
95 the architecture, variant or platform HAL, depending on where the
96 caches are implemented for the target. Often there will be a generic
97 implementation of the cache control macros in the architecture HAL
98 with the ability to override or undefine them in the variant or
99 platform HAL. Even when the implementation of the cache macros is in
100 the architecture HAL, the cache dimensions will be defined in the
101 variant or platform HAL. As with other files, the variant or platform
102 specific definitions are usually found in
105 >cyg/hal/var_cache.h</TT
109 >cyg/hal/plf_cache.h</TT
110 > respectively. These files
111 are include automatically by this header, so need not be included
114 >There are versions of the macros defined here for both the Data and
115 Instruction caches. these are distinguished by the use of either
123 names. Some architectures have a unified cache, where both data and
124 instruction share the same cache. In these cases the control macros
135 > macros will just be calls to the
139 > version. In the following descriptions,
143 > is used to stand for any of these. Where
144 there are issues specific to a particular cache, this will be
145 explained in the text.</P
147 >There might be target specific restrictions on the use of some of the
148 macros which it is the user's responsibility to comply with. Such
149 restrictions are documented in the header file with the macro
152 >Note that destructive cache macros should be used with caution.
153 Preceding a cache invalidation with a cache synchronization is not
154 safe in itself since an interrupt may happen after the synchronization
155 but before the invalidation. This might cause the state of dirty data
156 lines created during the interrupt to be lost.</P
158 >Depending on the architecture's capabilities, it may be possible to
159 temporarily disable the cache while doing the synchronization and
160 invalidation which solves the problem (no new data would be cached
161 during an interrupt). Otherwise it is necessary to disable interrupts
162 while manipulating the cache which may take a long time.</P
164 >Some platform HALs now support a pair of cache state query
167 >HAL_ICACHE_IS_ENABLED( x )</TT
171 >HAL_DCACHE_IS_ENABLED( x )</TT
172 > which set the argument
173 to true if the instruction or data cache is enabled,
174 respectively. Like most cache control macros, these are optional,
175 because the capabilities of different targets and boards can vary
176 considerably. Code which uses them, if it is to be considered
177 portable, should test for their existence first by means of
181 >. Be sure to include
184 ><cyg/hal/hal_cache.h></TT
185 > in order to do this
186 test and (maybe) use the macros.</P
192 NAME="AEN8115">Cache Dimensions</H2
200 CLASS="PROGRAMLISTING"
209 >These macros define the size and dimensions of the Instruction
220 >Defines the total size of the cache in bytes.</P
223 >HAL_XCACHE_LINE_SIZE</DT
226 >Defines the cache line size in bytes.</P
232 > Defines the number of ways in each set and defines its level
233 of associativity. This would be 1 for a direct mapped
234 cache, 2 for a 2-way cache, 4 for 4-way and so on.
241 > Defines the number of sets in the cache, and is calculated from
253 NAME="AEN8136">Global Cache Control</H2
261 CLASS="PROGRAMLISTING"
264 HAL_XCACHE_INVALIDATE_ALL()
266 HAL_XCACHE_BURST_SIZE( size )
267 HAL_DCACHE_WRITE_MODE( mode )
268 HAL_XCACHE_LOCK( base, size )
269 HAL_XCACHE_UNLOCK( base, size )
270 HAL_XCACHE_UNLOCK_ALL()</PRE
275 >These macros affect the state of the entire cache, or a large part of
283 >HAL_XCACHE_ENABLE() and HAL_XCACHE_DISABLE()</DT
286 >Enable and disable the cache.</P
289 >HAL_XCACHE_INVALIDATE_ALL()</DT
292 > Causes the entire contents of the cache to be invalidated.
293 Depending on the hardware, this may require the cache to be disabled
294 during the invalidation process. If so, the implementation must
297 >HAL_XCACHE_IS_ENABLED()</TT
299 restore the previous state.
308 > If this macro is called after
311 >HAL_XCACHE_SYNC()</TT
312 > with the intention of clearing
313 the cache (invalidating the cache after writing dirty data back to
314 memory), you must prevent interrupts from happening between the two
324 CLASS="PROGRAMLISTING"
326 HAL_DISABLE_INTERRUPTS(old);
328 HAL_XCACHE_INVALIDATE_ALL();
329 HAL_RESTORE_INTERRUPTS(old);
335 > Since the operation may take a very long time, real-time
336 responsiveness could be affected, so only do this when it is
337 absolutely required and you know the delay will not interfere
338 with the operation of drivers or the application.
344 >HAL_XCACHE_SYNC()</DT
347 > Causes the contents of the cache to be brought into synchronization
348 with the contents of memory. In some implementations this may be
351 >HAL_XCACHE_INVALIDATE_ALL()</TT
356 >HAL_XCACHE_BURST_SIZE()</DT
359 > Allows the size of cache to/from memory bursts to
360 be controlled. This macro will only be defined if this functionality
365 >HAL_DCACHE_WRITE_MODE()</DT
368 > Controls the way in which data cache lines are written back to
369 memory. There will be definitions for the possible
370 modes. Typical definitions are
373 >HAL_DCACHE_WRITEBACK_MODE</TT
377 >HAL_DCACHE_WRITETHRU_MODE</TT
379 only be defined if this functionality is available.
383 >HAL_XCACHE_LOCK()</DT
386 > Causes data to be locked into the cache. The base and size
387 arguments define the memory region that will be locked into the
388 cache. It is architecture dependent whether more than one locked
389 region is allowed at any one time, and whether this operation
390 causes the cache to cease acting as a cache for addresses
391 outside the region during the duration of the lock. This macro
392 will only be defined if this functionality is available.
396 >HAL_XCACHE_UNLOCK()</DT
399 > Cancels the locking of the memory region given. This should
400 normally correspond to a region supplied in a matching lock
401 call. This macro will only be defined if this functionality is
406 >HAL_XCACHE_UNLOCK_ALL()</DT
409 > Cancels all existing locked memory regions. This may be required
410 as part of the cache initialization on some architectures. This
411 macro will only be defined if this functionality is available.
422 NAME="AEN8182">Cache Line Control</H2
430 CLASS="PROGRAMLISTING"
431 >HAL_DCACHE_ALLOCATE( base , size )
432 HAL_DCACHE_FLUSH( base , size )
433 HAL_XCACHE_INVALIDATE( base , size )
434 HAL_DCACHE_STORE( base , size )
435 HAL_DCACHE_READ_HINT( base , size )
436 HAL_DCACHE_WRITE_HINT( base , size )
437 HAL_DCACHE_ZERO( base , size )</PRE
442 >All of these macros apply a cache operation to all cache lines that
443 match the memory address region defined by the base and size
444 arguments. These macros will only be defined if the described
445 functionality is available. Also, it is not guaranteed that the cache
446 function will only be applied to just the described regions, in some
447 architectures it may be applied to the whole cache.</P
454 >HAL_DCACHE_ALLOCATE()</DT
457 > Allocates lines in the cache for the given region without
458 reading their contents from memory, hence the contents of the lines
459 is undefined. This is useful for preallocating lines which are to
460 be completely overwritten, for example in a block copy
465 >HAL_DCACHE_FLUSH()</DT
468 > Invalidates all cache lines in the region after writing any
469 dirty lines to memory.
473 >HAL_XCACHE_INVALIDATE()</DT
476 > Invalidates all cache lines in the region. Any dirty lines
477 are invalidated without being written to memory.
481 >HAL_DCACHE_STORE()</DT
484 > Writes all dirty lines in the region to memory, but does not
485 invalidate any lines.
489 >HAL_DCACHE_READ_HINT()</DT
492 > Hints to the cache that the region is going to be read from
493 in the near future. This may cause the region to be speculatively
498 >HAL_DCACHE_WRITE_HINT()</DT
501 > Hints to the cache that the region is going to be written
502 to in the near future. This may have the identical behavior to
503 HAL_DCACHE_READ_HINT().
507 >HAL_DCACHE_ZERO()</DT
510 > Allocates and zeroes lines in the cache for the given
511 region without reading memory. This is useful if a large area of
512 memory is to be cleared.
524 SUMMARY="Footer navigation table"
535 HREF="hal-input-and-output.html"
553 HREF="hal-linker-scripts.html"
569 HREF="hal-interfaces.html"
projects / karo-tx-redboot.git / blob