+++ /dev/null
-<!-- Copyright (C) 2003 Red Hat, Inc. -->
-<!-- This material may be distributed only subject to the terms -->
-<!-- and conditions set forth in the Open Publication License, v1.0 -->
-<!-- or later (the latest version is presently available at -->
-<!-- http://www.opencontent.org/openpub/). -->
-<!-- Distribution of the work or derivative of the work in any -->
-<!-- standard (paper) book form is prohibited unless prior -->
-<!-- permission is obtained from the copyright holder. -->
-<HTML
-><HEAD
-><TITLE
->Cache Control</TITLE
-><meta name="MSSmartTagsPreventParsing" content="TRUE">
-<META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="eCos Reference Manual"
-HREF="ecos-ref.html"><LINK
-REL="UP"
-TITLE="HAL Interfaces"
-HREF="hal-interfaces.html"><LINK
-REL="PREVIOUS"
-TITLE="HAL I/O"
-HREF="hal-input-and-output.html"><LINK
-REL="NEXT"
-TITLE="Linker Scripts"
-HREF="hal-linker-scripts.html"></HEAD
-><BODY
-CLASS="SECTION"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->eCos Reference Manual</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="hal-input-and-output.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
->Chapter 9. HAL Interfaces</TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="hal-linker-scripts.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="SECTION"
-><H1
-CLASS="SECTION"
-><A
-NAME="HAL-CACHE-CONTROL">Cache Control</H1
-><P
->This section contains definitions for supporting control
-of the caches on the CPU.</P
-><P
->These definitions are usually found in the header file
-<TT
-CLASS="FILENAME"
->cyg/hal/hal_cache.h</TT
->. This file may be defined in
-the architecture, variant or platform HAL, depending on where the
-caches are implemented for the target. Often there will be a generic
-implementation of the cache control macros in the architecture HAL
-with the ability to override or undefine them in the variant or
-platform HAL. Even when the implementation of the cache macros is in
-the architecture HAL, the cache dimensions will be defined in the
-variant or platform HAL. As with other files, the variant or platform
-specific definitions are usually found in
-<TT
-CLASS="FILENAME"
->cyg/hal/var_cache.h</TT
-> and
-<TT
-CLASS="FILENAME"
->cyg/hal/plf_cache.h</TT
-> respectively. These files
-are include automatically by this header, so need not be included
-explicitly.</P
-><P
->There are versions of the macros defined here for both the Data and
-Instruction caches. these are distinguished by the use of either
-<TT
-CLASS="LITERAL"
->DCACHE</TT
-> or <TT
-CLASS="LITERAL"
->ICACHE</TT
-> in the macro
-names. Some architectures have a unified cache, where both data and
-instruction share the same cache. In these cases the control macros
-use <TT
-CLASS="LITERAL"
->UCACHE</TT
-> and the <TT
-CLASS="LITERAL"
->DCACHE</TT
-> and
-<TT
-CLASS="LITERAL"
->ICACHE</TT
-> macros will just be calls to the
-<TT
-CLASS="LITERAL"
->UCACHE</TT
-> version. In the following descriptions,
-<TT
-CLASS="LITERAL"
->XCACHE</TT
-> is used to stand for any of these. Where
-there are issues specific to a particular cache, this will be
-explained in the text.</P
-><P
->There might be target specific restrictions on the use of some of the
-macros which it is the user's responsibility to comply with. Such
-restrictions are documented in the header file with the macro
-definition.</P
-><P
->Note that destructive cache macros should be used with caution.
-Preceding a cache invalidation with a cache synchronization is not
-safe in itself since an interrupt may happen after the synchronization
-but before the invalidation. This might cause the state of dirty data
-lines created during the interrupt to be lost.</P
-><P
->Depending on the architecture's capabilities, it may be possible to
-temporarily disable the cache while doing the synchronization and
-invalidation which solves the problem (no new data would be cached
-during an interrupt). Otherwise it is necessary to disable interrupts
-while manipulating the cache which may take a long time.</P
-><P
->Some platform HALs now support a pair of cache state query
-macros: <TT
-CLASS="FUNCTION"
->HAL_ICACHE_IS_ENABLED( x )</TT
-> and
-<TT
-CLASS="FUNCTION"
->HAL_DCACHE_IS_ENABLED( x )</TT
-> which set the argument
-to true if the instruction or data cache is enabled,
-respectively. Like most cache control macros, these are optional,
-because the capabilities of different targets and boards can vary
-considerably. Code which uses them, if it is to be considered
-portable, should test for their existence first by means of
-<TT
-CLASS="LITERAL"
->#ifdef</TT
->. Be sure to include
-<TT
-CLASS="FILENAME"
-><cyg/hal/hal_cache.h></TT
-> in order to do this
-test and (maybe) use the macros.</P
-><DIV
-CLASS="SECTION"
-><H2
-CLASS="SECTION"
-><A
-NAME="AEN8115">Cache Dimensions</H2
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->HAL_XCACHE_SIZE
-HAL_XCACHE_LINE_SIZE
-HAL_XCACHE_WAYS
-HAL_XCACHE_SETS</PRE
-></TD
-></TR
-></TABLE
-><P
->These macros define the size and dimensions of the Instruction
-and Data caches.</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->HAL_XCACHE_SIZE</DT
-><DD
-><P
->Defines the total size of the cache in bytes.</P
-></DD
-><DT
->HAL_XCACHE_LINE_SIZE</DT
-><DD
-><P
->Defines the cache line size in bytes.</P
-></DD
-><DT
->HAL_XCACHE_WAYS</DT
-><DD
-><P
-> Defines the number of ways in each set and defines its level
- of associativity. This would be 1 for a direct mapped
- cache, 2 for a 2-way cache, 4 for 4-way and so on.
- </P
-></DD
-><DT
->HAL_XCACHE_SETS</DT
-><DD
-><P
-> Defines the number of sets in the cache, and is calculated from
- the previous values.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECTION"
-><H2
-CLASS="SECTION"
-><A
-NAME="AEN8136">Global Cache Control</H2
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->HAL_XCACHE_ENABLE()
-HAL_XCACHE_DISABLE()
-HAL_XCACHE_INVALIDATE_ALL()
-HAL_XCACHE_SYNC()
-HAL_XCACHE_BURST_SIZE( size )
-HAL_DCACHE_WRITE_MODE( mode )
-HAL_XCACHE_LOCK( base, size )
-HAL_XCACHE_UNLOCK( base, size )
-HAL_XCACHE_UNLOCK_ALL()</PRE
-></TD
-></TR
-></TABLE
-><P
->These macros affect the state of the entire cache, or a large part of
-it.</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->HAL_XCACHE_ENABLE() and HAL_XCACHE_DISABLE()</DT
-><DD
-><P
->Enable and disable the cache.</P
-></DD
-><DT
->HAL_XCACHE_INVALIDATE_ALL()</DT
-><DD
-><P
-> Causes the entire contents of the cache to be invalidated.
- Depending on the hardware, this may require the cache to be disabled
- during the invalidation process. If so, the implementation must
- use <TT
-CLASS="FUNCTION"
->HAL_XCACHE_IS_ENABLED()</TT
-> to save and
- restore the previous state.
- </P
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
-> If this macro is called after
- <TT
-CLASS="FUNCTION"
->HAL_XCACHE_SYNC()</TT
-> with the intention of clearing
- the cache (invalidating the cache after writing dirty data back to
- memory), you must prevent interrupts from happening between the two
- calls:
- </P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> ...
- HAL_DISABLE_INTERRUPTS(old);
- HAL_XCACHE_SYNC();
- HAL_XCACHE_INVALIDATE_ALL();
- HAL_RESTORE_INTERRUPTS(old);
- ...</PRE
-></TD
-></TR
-></TABLE
-><P
-> Since the operation may take a very long time, real-time
- responsiveness could be affected, so only do this when it is
- absolutely required and you know the delay will not interfere
- with the operation of drivers or the application.
- </P
-></BLOCKQUOTE
-></DIV
-></DD
-><DT
->HAL_XCACHE_SYNC()</DT
-><DD
-><P
-> Causes the contents of the cache to be brought into synchronization
- with the contents of memory. In some implementations this may be
- equivalent to <TT
-CLASS="FUNCTION"
->HAL_XCACHE_INVALIDATE_ALL()</TT
->.
- </P
-></DD
-><DT
->HAL_XCACHE_BURST_SIZE()</DT
-><DD
-><P
-> Allows the size of cache to/from memory bursts to
- be controlled. This macro will only be defined if this functionality
- is available.
- </P
-></DD
-><DT
->HAL_DCACHE_WRITE_MODE()</DT
-><DD
-><P
-> Controls the way in which data cache lines are written back to
- memory. There will be definitions for the possible
- modes. Typical definitions are
- <TT
-CLASS="LITERAL"
->HAL_DCACHE_WRITEBACK_MODE</TT
-> and
- <TT
-CLASS="LITERAL"
->HAL_DCACHE_WRITETHRU_MODE</TT
->. This macro will
- only be defined if this functionality is available.
- </P
-></DD
-><DT
->HAL_XCACHE_LOCK()</DT
-><DD
-><P
-> Causes data to be locked into the cache. The base and size
- arguments define the memory region that will be locked into the
- cache. It is architecture dependent whether more than one locked
- region is allowed at any one time, and whether this operation
- causes the cache to cease acting as a cache for addresses
- outside the region during the duration of the lock. This macro
- will only be defined if this functionality is available.
- </P
-></DD
-><DT
->HAL_XCACHE_UNLOCK()</DT
-><DD
-><P
-> Cancels the locking of the memory region given. This should
- normally correspond to a region supplied in a matching lock
- call. This macro will only be defined if this functionality is
- available.
- </P
-></DD
-><DT
->HAL_XCACHE_UNLOCK_ALL()</DT
-><DD
-><P
-> Cancels all existing locked memory regions. This may be required
- as part of the cache initialization on some architectures. This
- macro will only be defined if this functionality is available.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECTION"
-><H2
-CLASS="SECTION"
-><A
-NAME="AEN8182">Cache Line Control</H2
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->HAL_DCACHE_ALLOCATE( base , size )
-HAL_DCACHE_FLUSH( base , size )
-HAL_XCACHE_INVALIDATE( base , size )
-HAL_DCACHE_STORE( base , size )
-HAL_DCACHE_READ_HINT( base , size )
-HAL_DCACHE_WRITE_HINT( base , size )
-HAL_DCACHE_ZERO( base , size )</PRE
-></TD
-></TR
-></TABLE
-><P
->All of these macros apply a cache operation to all cache lines that
-match the memory address region defined by the base and size
-arguments. These macros will only be defined if the described
-functionality is available. Also, it is not guaranteed that the cache
-function will only be applied to just the described regions, in some
-architectures it may be applied to the whole cache.</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->HAL_DCACHE_ALLOCATE()</DT
-><DD
-><P
-> Allocates lines in the cache for the given region without
- reading their contents from memory, hence the contents of the lines
- is undefined. This is useful for preallocating lines which are to
- be completely overwritten, for example in a block copy
- operation.
- </P
-></DD
-><DT
->HAL_DCACHE_FLUSH()</DT
-><DD
-><P
-> Invalidates all cache lines in the region after writing any
- dirty lines to memory.
- </P
-></DD
-><DT
->HAL_XCACHE_INVALIDATE()</DT
-><DD
-><P
-> Invalidates all cache lines in the region. Any dirty lines
- are invalidated without being written to memory.
- </P
-></DD
-><DT
->HAL_DCACHE_STORE()</DT
-><DD
-><P
-> Writes all dirty lines in the region to memory, but does not
- invalidate any lines.
- </P
-></DD
-><DT
->HAL_DCACHE_READ_HINT()</DT
-><DD
-><P
-> Hints to the cache that the region is going to be read from
- in the near future. This may cause the region to be speculatively
- read into the cache.
- </P
-></DD
-><DT
->HAL_DCACHE_WRITE_HINT()</DT
-><DD
-><P
-> Hints to the cache that the region is going to be written
- to in the near future. This may have the identical behavior to
- HAL_DCACHE_READ_HINT().
- </P
-></DD
-><DT
->HAL_DCACHE_ZERO()</DT
-><DD
-><P
-> Allocates and zeroes lines in the cache for the given
- region without reading memory. This is useful if a large area of
- memory is to be cleared.
- </P
-></DD
-></DL
-></DIV
-></DIV
-></DIV
-><DIV
-CLASS="NAVFOOTER"
-><HR
-ALIGN="LEFT"
-WIDTH="100%"><TABLE
-SUMMARY="Footer navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
-><A
-HREF="hal-input-and-output.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="ecos-ref.html"
-ACCESSKEY="H"
->Home</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
-><A
-HREF="hal-linker-scripts.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->HAL I/O</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="hal-interfaces.html"
-ACCESSKEY="U"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->Linker Scripts</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff