URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [hal-cache-control.html] - Blame information for rev 811

Go to most recent revision | Details | Compare with Previous | View Log


<!-- 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"
>&lt;cyg/hal/hal_cache.h&gt;</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
>

Line No.	Rev	Author	Line
1	28	unneback	`<!-- 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. -->`
9			`<HTML`
10			`><HEAD`
11			`><TITLE`
12			`>Cache Control</TITLE`
13			`><meta name="MSSmartTagsPreventParsing" content="TRUE">`
14			`<META`
15			`NAME="GENERATOR"`
16			`CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+`
17			`"><LINK`
18			`REL="HOME"`
19			`TITLE="eCos Reference Manual"`
20			`HREF="ecos-ref.html"><LINK`
21			`REL="UP"`
22			`TITLE="HAL Interfaces"`
23			`HREF="hal-interfaces.html"><LINK`
24			`REL="PREVIOUS"`
25			`TITLE="HAL I/O"`
26			`HREF="hal-input-and-output.html"><LINK`
27			`REL="NEXT"`
28			`TITLE="Linker Scripts"`
29			`HREF="hal-linker-scripts.html"></HEAD`
30			`><BODY`
31			`CLASS="SECTION"`
32			`BGCOLOR="#FFFFFF"`
33			`TEXT="#000000"`
34			`LINK="#0000FF"`
35			`VLINK="#840084"`
36			`ALINK="#0000FF"`
37			`><DIV`
38			`CLASS="NAVHEADER"`
39			`><TABLE`
40			`SUMMARY="Header navigation table"`
41			`WIDTH="100%"`
42			`BORDER="0"`
43			`CELLPADDING="0"`
44			`CELLSPACING="0"`
45			`><TR`
46			`><TH`
47			`COLSPAN="3"`
48			`ALIGN="center"`
49			`>eCos Reference Manual</TH`
50			`></TR`
51			`><TR`
52			`><TD`
53			`WIDTH="10%"`
54			`ALIGN="left"`
55			`VALIGN="bottom"`
56			`><A`
57			`HREF="hal-input-and-output.html"`
58			`ACCESSKEY="P"`
59			`>Prev</A`
60			`></TD`
61			`><TD`
62			`WIDTH="80%"`
63			`ALIGN="center"`
64			`VALIGN="bottom"`
65			`>Chapter 9. HAL Interfaces</TD`
66			`><TD`
67			`WIDTH="10%"`
68			`ALIGN="right"`
69			`VALIGN="bottom"`
70			`><A`
71			`HREF="hal-linker-scripts.html"`
72			`ACCESSKEY="N"`
73			`>Next</A`
74			`></TD`
75			`></TR`
76			`></TABLE`
77			`><HR`
78			`ALIGN="LEFT"`
79			`WIDTH="100%"></DIV`
80			`><DIV`
81			`CLASS="SECTION"`
82			`><H1`
83			`CLASS="SECTION"`
84			`><A`
85			`NAME="HAL-CACHE-CONTROL">Cache Control</H1`
86			`><P`
87			`>This section contains definitions for supporting control`
88			`of the caches on the CPU.</P`
89			`><P`
90			`>These definitions are usually found in the header file`
91			`<TT`
92			`CLASS="FILENAME"`
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`
103			`<TT`
104			`CLASS="FILENAME"`
105			`>cyg/hal/var_cache.h</TT`
106			`> and`
107			`<TT`
108			`CLASS="FILENAME"`
109			`>cyg/hal/plf_cache.h</TT`
110			`> respectively. These files`
111			`are include automatically by this header, so need not be included`
112			`explicitly.</P`
113			`><P`
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`
116			`<TT`
117			`CLASS="LITERAL"`
118			`>DCACHE</TT`
119			`> or <TT`
120			`CLASS="LITERAL"`
121			`>ICACHE</TT`
122			`> in the macro`
123			`names. Some architectures have a unified cache, where both data and`
124			`instruction share the same cache. In these cases the control macros`
125			`use <TT`
126			`CLASS="LITERAL"`
127			`>UCACHE</TT`
128			`> and the <TT`
129			`CLASS="LITERAL"`
130			`>DCACHE</TT`
131			`> and`
132			`<TT`
133			`CLASS="LITERAL"`
134			`>ICACHE</TT`
135			`> macros will just be calls to the`
136			`<TT`
137			`CLASS="LITERAL"`
138			`>UCACHE</TT`
139			`> version. In the following descriptions,`
140			`<TT`
141			`CLASS="LITERAL"`
142			`>XCACHE</TT`
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`
146			`><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`
150			`definition.</P`
151			`><P`
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`
157			`><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`
163			`><P`
164			`>Some platform HALs now support a pair of cache state query`
165			`macros: <TT`
166			`CLASS="FUNCTION"`
167			`>HAL_ICACHE_IS_ENABLED( x )</TT`
168			`> and`
169			`<TT`
170			`CLASS="FUNCTION"`
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`
178			`<TT`
179			`CLASS="LITERAL"`
180			`>#ifdef</TT`
181			`>. Be sure to include`
182			`<TT`
183			`CLASS="FILENAME"`
184			`><cyg/hal/hal_cache.h></TT`
185			`> in order to do this`
186			`test and (maybe) use the macros.</P`
187			`><DIV`
188			`CLASS="SECTION"`
189			`><H2`
190			`CLASS="SECTION"`
191			`><A`
192			`NAME="AEN8115">Cache Dimensions</H2`
193			`><TABLE`
194			`BORDER="5"`
195			`BGCOLOR="#E0E0F0"`
196			`WIDTH="70%"`
197			`><TR`
198			`><TD`
199			`><PRE`
200			`CLASS="PROGRAMLISTING"`
201			`>HAL_XCACHE_SIZE`
202			`HAL_XCACHE_LINE_SIZE`
203			`HAL_XCACHE_WAYS`
204			`HAL_XCACHE_SETS</PRE`
205			`></TD`
206			`></TR`
207			`></TABLE`
208			`><P`
209			`>These macros define the size and dimensions of the Instruction`
210			`and Data caches.</P`
211			`><P`
212			`></P`
213			`><DIV`
214			`CLASS="VARIABLELIST"`
215			`><DL`
216			`><DT`
217			`>HAL_XCACHE_SIZE</DT`
218			`><DD`
219			`><P`
220			`>Defines the total size of the cache in bytes.</P`
221			`></DD`
222			`><DT`
223			`>HAL_XCACHE_LINE_SIZE</DT`
224			`><DD`
225			`><P`
226			`>Defines the cache line size in bytes.</P`
227			`></DD`
228			`><DT`
229			`>HAL_XCACHE_WAYS</DT`
230			`><DD`
231			`><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.`
235			`</P`
236			`></DD`
237			`><DT`
238			`>HAL_XCACHE_SETS</DT`
239			`><DD`
240			`><P`
241			`> Defines the number of sets in the cache, and is calculated from`
242			`the previous values.`
243			`</P`
244			`></DD`
245			`></DL`
246			`></DIV`
247			`></DIV`
248			`><DIV`
249			`CLASS="SECTION"`
250			`><H2`
251			`CLASS="SECTION"`
252			`><A`
253			`NAME="AEN8136">Global Cache Control</H2`
254			`><TABLE`
255			`BORDER="5"`
256			`BGCOLOR="#E0E0F0"`
257			`WIDTH="70%"`
258			`><TR`
259			`><TD`
260			`><PRE`
261			`CLASS="PROGRAMLISTING"`
262			`>HAL_XCACHE_ENABLE()`
263			`HAL_XCACHE_DISABLE()`
264			`HAL_XCACHE_INVALIDATE_ALL()`
265			`HAL_XCACHE_SYNC()`
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`
271			`></TD`
272			`></TR`
273			`></TABLE`
274			`><P`
275			`>These macros affect the state of the entire cache, or a large part of`
276			`it.</P`
277			`><P`
278			`></P`
279			`><DIV`
280			`CLASS="VARIABLELIST"`
281			`><DL`
282			`><DT`
283			`>HAL_XCACHE_ENABLE() and HAL_XCACHE_DISABLE()</DT`
284			`><DD`
285			`><P`
286			`>Enable and disable the cache.</P`
287			`></DD`
288			`><DT`
289			`>HAL_XCACHE_INVALIDATE_ALL()</DT`
290			`><DD`
291			`><P`
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`
295			`use <TT`
296			`CLASS="FUNCTION"`
297			`>HAL_XCACHE_IS_ENABLED()</TT`
298			`> to save and`
299			`restore the previous state.`
300			`</P`
301			`><DIV`
302			`CLASS="NOTE"`
303			`><BLOCKQUOTE`
304			`CLASS="NOTE"`
305			`><P`
306			`><B`
307			`>Note: </B`
308			`> If this macro is called after`
309			`<TT`
310			`CLASS="FUNCTION"`
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`
315			`calls:`
316			`</P`
317			`><TABLE`
318			`BORDER="5"`
319			`BGCOLOR="#E0E0F0"`
320			`WIDTH="70%"`
321			`><TR`
322			`><TD`
323			`><PRE`
324			`CLASS="PROGRAMLISTING"`
325			`> ...`
326			`HAL_DISABLE_INTERRUPTS(old);`
327			`HAL_XCACHE_SYNC();`
328			`HAL_XCACHE_INVALIDATE_ALL();`
329			`HAL_RESTORE_INTERRUPTS(old);`
330			`...</PRE`
331			`></TD`
332			`></TR`
333			`></TABLE`
334			`><P`
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.`
339			`</P`
340			`></BLOCKQUOTE`
341			`></DIV`
342			`></DD`
343			`><DT`
344			`>HAL_XCACHE_SYNC()</DT`
345			`><DD`
346			`><P`
347			`> Causes the contents of the cache to be brought into synchronization`
348			`with the contents of memory. In some implementations this may be`
349			`equivalent to <TT`
350			`CLASS="FUNCTION"`
351			`>HAL_XCACHE_INVALIDATE_ALL()</TT`
352			`>.`
353			`</P`
354			`></DD`
355			`><DT`
356			`>HAL_XCACHE_BURST_SIZE()</DT`
357			`><DD`
358			`><P`
359			`> Allows the size of cache to/from memory bursts to`
360			`be controlled. This macro will only be defined if this functionality`
361			`is available.`
362			`</P`
363			`></DD`
364			`><DT`
365			`>HAL_DCACHE_WRITE_MODE()</DT`
366			`><DD`
367			`><P`
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`
371			`<TT`
372			`CLASS="LITERAL"`
373			`>HAL_DCACHE_WRITEBACK_MODE</TT`
374			`> and`
375			`<TT`
376			`CLASS="LITERAL"`
377			`>HAL_DCACHE_WRITETHRU_MODE</TT`
378			`>. This macro will`
379			`only be defined if this functionality is available.`
380			`</P`
381			`></DD`
382			`><DT`
383			`>HAL_XCACHE_LOCK()</DT`
384			`><DD`
385			`><P`
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.`
393			`</P`
394			`></DD`
395			`><DT`
396			`>HAL_XCACHE_UNLOCK()</DT`
397			`><DD`
398			`><P`
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`
402			`available.`
403			`</P`
404			`></DD`
405			`><DT`
406			`>HAL_XCACHE_UNLOCK_ALL()</DT`
407			`><DD`
408			`><P`
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.`
412			`</P`
413			`></DD`
414			`></DL`
415			`></DIV`
416			`></DIV`
417			`><DIV`
418			`CLASS="SECTION"`
419			`><H2`
420			`CLASS="SECTION"`
421			`><A`
422			`NAME="AEN8182">Cache Line Control</H2`
423			`><TABLE`
424			`BORDER="5"`
425			`BGCOLOR="#E0E0F0"`
426			`WIDTH="70%"`
427			`><TR`
428			`><TD`
429			`><PRE`
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`
438			`></TD`
439			`></TR`
440			`></TABLE`
441			`><P`
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`
448			`><P`
449			`></P`
450			`><DIV`
451			`CLASS="VARIABLELIST"`
452			`><DL`
453			`><DT`
454			`>HAL_DCACHE_ALLOCATE()</DT`
455			`><DD`
456			`><P`
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`
461			`operation.`
462			`</P`
463			`></DD`
464			`><DT`
465			`>HAL_DCACHE_FLUSH()</DT`
466			`><DD`
467			`><P`
468			`> Invalidates all cache lines in the region after writing any`
469			`dirty lines to memory.`
470			`</P`
471			`></DD`
472			`><DT`
473			`>HAL_XCACHE_INVALIDATE()</DT`
474			`><DD`
475			`><P`
476			`> Invalidates all cache lines in the region. Any dirty lines`
477			`are invalidated without being written to memory.`
478			`</P`
479			`></DD`
480			`><DT`
481			`>HAL_DCACHE_STORE()</DT`
482			`><DD`
483			`><P`
484			`> Writes all dirty lines in the region to memory, but does not`
485			`invalidate any lines.`
486			`</P`
487			`></DD`
488			`><DT`
489			`>HAL_DCACHE_READ_HINT()</DT`
490			`><DD`
491			`><P`
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`
494			`read into the cache.`
495			`</P`
496			`></DD`
497			`><DT`
498			`>HAL_DCACHE_WRITE_HINT()</DT`
499			`><DD`
500			`><P`

Browse

Tools

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [hal-cache-control.html] - Blame information for rev 811