[rtems-central commit] spec: Document the cache manager
Sebastian Huber
sebh at rtems.org
Wed Sep 15 06:02:35 UTC 2021
Module: rtems-central
Branch: master
Commit: 4644a832cacce5a2ea665d091c26af5df61965be
Changeset: http://git.rtems.org/rtems-central/commit/?id=4644a832cacce5a2ea665d091c26af5df61965be
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Sep 8 14:35:10 2021 +0200
spec: Document the cache manager
---
config.yml | 3 ++
spec/rtems/cache/if/aligned-malloc.yml | 21 +++++++----
spec/rtems/cache/if/coherent-add-area.yml | 18 +++++----
spec/rtems/cache/if/coherent-allocate.yml | 44 +++++++++++++++++-----
spec/rtems/cache/if/coherent-free.yml | 11 +++---
spec/rtems/cache/if/disable-data.yml | 6 +--
spec/rtems/cache/if/disable-instruction.yml | 6 +--
spec/rtems/cache/if/enable-data.yml | 6 +--
spec/rtems/cache/if/enable-instruction.yml | 6 +--
spec/rtems/cache/if/flush-entire-data.yml | 6 +--
spec/rtems/cache/if/flush-multiple-data-lines.yml | 18 +++++----
spec/rtems/cache/if/freeze-data.yml | 8 ++--
spec/rtems/cache/if/freeze-instruction.yml | 8 ++--
spec/rtems/cache/if/get-data-line-size.yml | 15 +++++---
spec/rtems/cache/if/get-data-size.yml | 18 ++++++---
spec/rtems/cache/if/get-instruction-line-size.yml | 15 +++++---
spec/rtems/cache/if/get-instruction-size.yml | 18 ++++++---
spec/rtems/cache/if/get-maximal-line-size.yml | 17 ++++++---
spec/rtems/cache/if/group.yml | 40 +++++++++++++++++++-
.../if/instruction-sync-after-code-change.yml | 24 ++++++++----
spec/rtems/cache/if/invalidate-entire-data.yml | 6 +--
.../cache/if/invalidate-entire-instruction.yml | 6 +--
.../cache/if/invalidate-multiple-data-lines.yml | 24 ++++++++----
.../if/invalidate-multiple-instruction-lines.yml | 22 +++++++----
spec/rtems/cache/if/unfreeze-data.yml | 8 ++--
spec/rtems/cache/if/unfreeze-instruction.yml | 8 ++--
26 files changed, 256 insertions(+), 126 deletions(-)
diff --git a/config.yml b/config.yml
index 5374e1a..d928214 100644
--- a/config.yml
+++ b/config.yml
@@ -115,6 +115,9 @@ interface-documentation:
- directives-target: modules/rtems-docs/c-user/barrier/directives.rst
group: /rtems/barrier/if/group
introduction-target: modules/rtems-docs/c-user/barrier/introduction.rst
+- directives-target: modules/rtems-docs/c-user/cache/directives.rst
+ group: /rtems/cache/if/group
+ introduction-target: modules/rtems-docs/c-user/cache/introduction.rst
- directives-target: modules/rtems-docs/c-user/dual-ported-memory/directives.rst
group: /rtems/dpmem/if/group
introduction-target: modules/rtems-docs/c-user/dual-ported-memory/introduction.rst
diff --git a/spec/rtems/cache/if/aligned-malloc.yml b/spec/rtems/cache/if/aligned-malloc.yml
index 0f9b373..e1c68d6 100644
--- a/spec/rtems/cache/if/aligned-malloc.yml
+++ b/spec/rtems/cache/if/aligned-malloc.yml
@@ -1,8 +1,9 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Allocates memory from the C Program Heap which begins at a cache line
+ boundary.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -29,10 +30,16 @@ links:
name: rtems_cache_aligned_malloc
notes: null
params:
-- description: '%'
+- description: |
+ is the size in bytes of the memory area to allocate.
dir: null
- name: nbytes
+ name: size
return:
- return: null
- return-values: []
+ return: |
+ Returns the begin address of the allocated memory. The begin address is on
+ a cache line boundary.
+ return-values:
+ - description: |
+ There is not enough memory available to satisfy the allocation request.
+ value: ${/c/if/null:/name}
type: interface
diff --git a/spec/rtems/cache/if/coherent-add-area.yml b/spec/rtems/cache/if/coherent-add-area.yml
index e5b9cbc..f6c8949 100644
--- a/spec/rtems/cache/if/coherent-add-area.yml
+++ b/spec/rtems/cache/if/coherent-add-area.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Adds a cache coherent memory area to the cache coherent allocator.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -19,7 +19,7 @@ interface-type: function
links:
- role: interface-placement
uid: header
-- role: interface-ingroup
+- role: interface-ingroup-hidden
uid: group
- role: constraint
uid: /constraint/directive-ctx-devinit
@@ -30,12 +30,14 @@ links:
name: rtems_cache_coherent_add_area
notes: null
params:
-- description: '%'
+- description: |
+ is the begin address of the cache coherent memory area to add.
dir: null
- name: area_begin
-- description: '%'
+ name: begin
+- description: |
+ is the size in bytes of the cache coherent memory area to add.
dir: null
- name: area_size
+ name: size
return:
return: null
return-values: []
diff --git a/spec/rtems/cache/if/coherent-allocate.yml b/spec/rtems/cache/if/coherent-allocate.yml
index 4da8f4b..b087c71 100644
--- a/spec/rtems/cache/if/coherent-allocate.yml
+++ b/spec/rtems/cache/if/coherent-allocate.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Allocates a memory area from cache coherent memory.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -20,7 +20,7 @@ interface-type: function
links:
- role: interface-placement
uid: header
-- role: interface-ingroup
+- role: interface-ingroup-hidden
uid: group
- role: constraint
uid: /constraint/directive-ctx-devinit
@@ -29,18 +29,42 @@ links:
- role: constraint
uid: /constraint/object-allocator
name: rtems_cache_coherent_allocate
-notes: null
+notes: |
+ A size value of zero will return a unique address which may be freed with
+ ${coherent-free:/name}.
+
+ The memory allocated by the directive may be released with a call to
+ ${coherent-free:/name}.
+
+ By default the C Program Heap allocator is used. In case special memory
+ areas must be used, then the ${/glossary/bsp:/term} or the application should
+ add cache coherent memory areas for the allocator via
+ ${coherent-add-area:/name}.
params:
-- description: '%'
+- description: |
+ is the requested size in bytes of the memory area to allocate.
dir: null
name: size
-- description: '%'
+- description: |
+ is the requested alignment in bytes of the memory area to allocate. If the
+ alignment parameter is not equal to zero, the allocated memory area will
+ begin at an address aligned by this value.
dir: null
name: alignment
-- description: '%'
+- description: |
+ is the requested boundary in bytes of the memory area to allocate. If the
+ boundary parameter is not equal to zero, the allocated memory area will
+ comply with a boundary constraint. The boundary value specifies the set of
+ addresses which are aligned by the boundary value. The interior of the
+ allocated memory area will not contain an element of this set. The begin
+ or end address of the area may be a member of the set.
dir: null
name: boundary
return:
- return: null
- return-values: []
+ return: |
+ Returns the begin address of the allocated memory.
+ return-values:
+ - description: |
+ There is not enough memory available to satisfy the allocation request.
+ value: ${/c/if/null:/name}
type: interface
diff --git a/spec/rtems/cache/if/coherent-free.yml b/spec/rtems/cache/if/coherent-free.yml
index c337990..1e849c1 100644
--- a/spec/rtems/cache/if/coherent-free.yml
+++ b/spec/rtems/cache/if/coherent-free.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Frees memory allocated by ${coherent-allocate:/name}.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -18,7 +18,7 @@ interface-type: function
links:
- role: interface-placement
uid: header
-- role: interface-ingroup
+- role: interface-ingroup-hidden
uid: group
- role: constraint
uid: /constraint/directive-ctx-devinit
@@ -29,7 +29,8 @@ links:
name: rtems_cache_coherent_free
notes: null
params:
-- description: '%'
+- description: |
+ is a pointer returned by ${coherent-allocate:/name}.
dir: null
name: ptr
return:
diff --git a/spec/rtems/cache/if/disable-data.yml b/spec/rtems/cache/if/disable-data.yml
index 2d4a3d5..488a194 100644
--- a/spec/rtems/cache/if/disable-data.yml
+++ b/spec/rtems/cache/if/disable-data.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Disables the data cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
diff --git a/spec/rtems/cache/if/disable-instruction.yml b/spec/rtems/cache/if/disable-instruction.yml
index 654fdf3..1b25334 100644
--- a/spec/rtems/cache/if/disable-instruction.yml
+++ b/spec/rtems/cache/if/disable-instruction.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Disables the instruction cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
diff --git a/spec/rtems/cache/if/enable-data.yml b/spec/rtems/cache/if/enable-data.yml
index 42fd953..e2637aa 100644
--- a/spec/rtems/cache/if/enable-data.yml
+++ b/spec/rtems/cache/if/enable-data.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Enables the data cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
diff --git a/spec/rtems/cache/if/enable-instruction.yml b/spec/rtems/cache/if/enable-instruction.yml
index d5ed248..c34333f 100644
--- a/spec/rtems/cache/if/enable-instruction.yml
+++ b/spec/rtems/cache/if/enable-instruction.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Enables the instruction cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
diff --git a/spec/rtems/cache/if/flush-entire-data.yml b/spec/rtems/cache/if/flush-entire-data.yml
index 707af38..c2a0fc9 100644
--- a/spec/rtems/cache/if/flush-entire-data.yml
+++ b/spec/rtems/cache/if/flush-entire-data.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Flushes the entire data cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
diff --git a/spec/rtems/cache/if/flush-multiple-data-lines.yml b/spec/rtems/cache/if/flush-multiple-data-lines.yml
index a110924..ac03301 100644
--- a/spec/rtems/cache/if/flush-multiple-data-lines.yml
+++ b/spec/rtems/cache/if/flush-multiple-data-lines.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Flushes the data cache lines covering the memory area.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -12,7 +12,9 @@ definition:
- ${/c/if/size_t:/name} ${.:/params[1]/name}
return: void
variants: []
-description: null
+description: |
+ Dirty data cache lines covering the area are transfered to memory. Depending
+ on the cache implementation this may mark the lines as invalid.
enabled-by: true
index-entries: []
interface-type: function
@@ -28,10 +30,12 @@ links:
name: rtems_cache_flush_multiple_data_lines
notes: null
params:
-- description: '%'
+- description: |
+ is the begin address of the memory area to flush.
dir: null
- name: addr
-- description: '%'
+ name: begin
+- description: |
+ is the size in bytes of the memory area to flush.
dir: null
name: size
return:
diff --git a/spec/rtems/cache/if/freeze-data.yml b/spec/rtems/cache/if/freeze-data.yml
index 99d8e7f..91e7f70 100644
--- a/spec/rtems/cache/if/freeze-data.yml
+++ b/spec/rtems/cache/if/freeze-data.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Freezes the data caches.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -17,7 +17,7 @@ interface-type: function
links:
- role: interface-placement
uid: header
-- role: interface-ingroup
+- role: interface-ingroup-hidden
uid: group
- role: constraint
uid: /constraint/directive-ctx-any
diff --git a/spec/rtems/cache/if/freeze-instruction.yml b/spec/rtems/cache/if/freeze-instruction.yml
index f2d578d..e1224b9 100644
--- a/spec/rtems/cache/if/freeze-instruction.yml
+++ b/spec/rtems/cache/if/freeze-instruction.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Freezes the instruction caches.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -17,7 +17,7 @@ interface-type: function
links:
- role: interface-placement
uid: header
-- role: interface-ingroup
+- role: interface-ingroup-hidden
uid: group
- role: constraint
uid: /constraint/directive-ctx-any
diff --git a/spec/rtems/cache/if/get-data-line-size.yml b/spec/rtems/cache/if/get-data-line-size.yml
index 0fda20d..cee4b71 100644
--- a/spec/rtems/cache/if/get-data-line-size.yml
+++ b/spec/rtems/cache/if/get-data-line-size.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Gets the data cache line size in bytes.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -27,6 +27,11 @@ name: rtems_cache_get_data_line_size
notes: null
params: []
return:
- return: null
- return-values: []
+ return: |
+ Returns the data cache line size in bytes. For multi-level caches this is
+ the maximum of the cache line sizes of all levels.
+ return-values:
+ - description: |
+ There is no data cache present.
+ value: 0
type: interface
diff --git a/spec/rtems/cache/if/get-data-size.yml b/spec/rtems/cache/if/get-data-size.yml
index 1a43029..70612b1 100644
--- a/spec/rtems/cache/if/get-data-size.yml
+++ b/spec/rtems/cache/if/get-data-size.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Gets the data cache size in bytes for the cache level.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -27,10 +27,16 @@ links:
name: rtems_cache_get_data_cache_size
notes: null
params:
-- description: '%'
+- description: |
+ is the requested data cache level. The cache level zero specifies the
+ entire data cache.
dir: null
name: level
return:
- return: null
- return-values: []
+ return: |
+ Returns the data cache size in bytes of the requested cache level.
+ return-values:
+ - description: |
+ There is no data cache present at the requested cache level.
+ value: 0
type: interface
diff --git a/spec/rtems/cache/if/get-instruction-line-size.yml b/spec/rtems/cache/if/get-instruction-line-size.yml
index ee883e0..76d1bd9 100644
--- a/spec/rtems/cache/if/get-instruction-line-size.yml
+++ b/spec/rtems/cache/if/get-instruction-line-size.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Gets the instruction cache line size in bytes.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -27,6 +27,11 @@ name: rtems_cache_get_instruction_line_size
notes: null
params: []
return:
- return: null
- return-values: []
+ return: |
+ Returns the instruction cache line size in bytes. For multi-level caches
+ this is the maximum of the cache line sizes of all levels.
+ return-values:
+ - description: |
+ There is no instruction cache present.
+ value: 0
type: interface
diff --git a/spec/rtems/cache/if/get-instruction-size.yml b/spec/rtems/cache/if/get-instruction-size.yml
index 3a31783..d48618d 100644
--- a/spec/rtems/cache/if/get-instruction-size.yml
+++ b/spec/rtems/cache/if/get-instruction-size.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Gets the instruction cache size in bytes for the cache level.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -27,10 +27,16 @@ links:
name: rtems_cache_get_instruction_cache_size
notes: null
params:
-- description: '%'
+- description: |
+ is the requested instruction cache level. The cache level zero specifies
+ the entire instruction cache.
dir: null
name: level
return:
- return: null
- return-values: []
+ return: |
+ Returns the instruction cache size in bytes of the requested cache level.
+ return-values:
+ - description: |
+ There is no instruction cache present at the requested cache level.
+ value: 0
type: interface
diff --git a/spec/rtems/cache/if/get-maximal-line-size.yml b/spec/rtems/cache/if/get-maximal-line-size.yml
index e231695..3a61674 100644
--- a/spec/rtems/cache/if/get-maximal-line-size.yml
+++ b/spec/rtems/cache/if/get-maximal-line-size.yml
@@ -1,8 +1,10 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Gets the maximal cache line size in bytes of all caches (data, instruction,
+ or unified).
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2016 Pavel Pisa
definition:
default:
attributes: null
@@ -27,6 +29,11 @@ name: rtems_cache_get_maximal_line_size
notes: null
params: []
return:
- return: null
- return-values: []
+ return: |
+ Returns the maximal cache line size in bytes of all caches (data,
+ instruction, or unified).
+ return-values:
+ - description: |
+ There is no cache present.
+ value: 0
type: interface
diff --git a/spec/rtems/cache/if/group.yml b/spec/rtems/cache/if/group.yml
index 80821f9..eede791 100644
--- a/spec/rtems/cache/if/group.yml
+++ b/spec/rtems/cache/if/group.yml
@@ -4,7 +4,11 @@ brief: |
data and instruction caches.
copyrights:
- Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de)
-description: null
+- Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR)
+description: |
+ The actual actions of the Cache Manager operations depend on the hardware and
+ the implementation provided by the CPU architecture port or a board support
+ package. Cache implementations tend to be highly hardware dependent.
enabled-by: true
identifier: RTEMSAPIClassicCache
index-entries: []
@@ -14,6 +18,40 @@ links:
uid: header
- role: interface-ingroup
uid: ../../if/group
+- role: placement-order
+ uid: flush-multiple-data-lines
+- role: placement-order
+ uid: invalidate-multiple-data-lines
+- role: placement-order
+ uid: invalidate-multiple-instruction-lines
+- role: placement-order
+ uid: instruction-sync-after-code-change
+- role: placement-order
+ uid: get-maximal-line-size
+- role: placement-order
+ uid: get-data-line-size
+- role: placement-order
+ uid: get-instruction-line-size
+- role: placement-order
+ uid: get-data-size
+- role: placement-order
+ uid: get-instruction-size
+- role: placement-order
+ uid: flush-entire-data
+- role: placement-order
+ uid: invalidate-entire-data
+- role: placement-order
+ uid: invalidate-entire-instruction
+- role: placement-order
+ uid: enable-data
+- role: placement-order
+ uid: disable-data
+- role: placement-order
+ uid: enable-instruction
+- role: placement-order
+ uid: disable-instruction
+- role: placement-order
+ uid: aligned-malloc
name: Cache Manager
text: |
The Classic API shall provide an interface to the Cache Manager.
diff --git a/spec/rtems/cache/if/instruction-sync-after-code-change.yml b/spec/rtems/cache/if/instruction-sync-after-code-change.yml
index a209173..ba04749 100644
--- a/spec/rtems/cache/if/instruction-sync-after-code-change.yml
+++ b/spec/rtems/cache/if/instruction-sync-after-code-change.yml
@@ -1,8 +1,9 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Ensures necessary synchronization required after code changes.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2016 Pavel Pisa
definition:
default:
attributes: null
@@ -26,14 +27,21 @@ links:
- role: constraint
uid: /constraint/directive-no-preempt
name: rtems_cache_instruction_sync_after_code_change
-notes: null
+notes: |
+ When code is loaded or modified, then most systems require synchronization
+ instructions to update the instruction caches so that the loaded or modified
+ code is fetched. For example, systems with separate data and instruction
+ caches or systems without instruction cache snooping. The directives should
+ be used by run time loader for example.
params:
-- description: '%'
+- description: |
+ is the begin address of the code area to synchronize.
dir: null
- name: code_addr
-- description: '%'
+ name: begin
+- description: |
+ is the size in bytes of the code area to synchronize.
dir: null
- name: n_bytes
+ name: size
return:
return: null
return-values: []
diff --git a/spec/rtems/cache/if/invalidate-entire-data.yml b/spec/rtems/cache/if/invalidate-entire-data.yml
index 770ca39..4d58d60 100644
--- a/spec/rtems/cache/if/invalidate-entire-data.yml
+++ b/spec/rtems/cache/if/invalidate-entire-data.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Invalidates the entire data cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
diff --git a/spec/rtems/cache/if/invalidate-entire-instruction.yml b/spec/rtems/cache/if/invalidate-entire-instruction.yml
index 8dedbb0..0610ff9 100644
--- a/spec/rtems/cache/if/invalidate-entire-instruction.yml
+++ b/spec/rtems/cache/if/invalidate-entire-instruction.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Invalidates the entire instruction cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
diff --git a/spec/rtems/cache/if/invalidate-multiple-data-lines.yml b/spec/rtems/cache/if/invalidate-multiple-data-lines.yml
index b69336e..d5710d6 100644
--- a/spec/rtems/cache/if/invalidate-multiple-data-lines.yml
+++ b/spec/rtems/cache/if/invalidate-multiple-data-lines.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Invalidates the data cache lines covering the memory area.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -12,7 +12,9 @@ definition:
- ${/c/if/size_t:/name} ${.:/params[1]/name}
return: void
variants: []
-description: null
+description: |
+ The cache lines covering the area are marked as invalid. A later read
+ access in the area will load the data from memory.
enabled-by: true
index-entries: []
interface-type: function
@@ -26,12 +28,18 @@ links:
- role: constraint
uid: /constraint/directive-no-preempt
name: rtems_cache_invalidate_multiple_data_lines
-notes: null
+notes: |
+ In case the area is not aligned on cache line boundaries, then this
+ operation may destroy unrelated data.
+
+ On some systems, the cache lines may be flushed before they are invalidated.
params:
-- description: '%'
+- description: |
+ is the begin address of the memory area to invalidate.
dir: null
- name: addr
-- description: '%'
+ name: begin
+- description: |
+ is the size in bytes of the memory area to invalidate.
dir: null
name: size
return:
diff --git a/spec/rtems/cache/if/invalidate-multiple-instruction-lines.yml b/spec/rtems/cache/if/invalidate-multiple-instruction-lines.yml
index 6f95de2..52e40d3 100644
--- a/spec/rtems/cache/if/invalidate-multiple-instruction-lines.yml
+++ b/spec/rtems/cache/if/invalidate-multiple-instruction-lines.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Invalidates the instruction cache lines covering the memory area.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -12,7 +12,9 @@ definition:
- ${/c/if/size_t:/name} ${.:/params[1]/name}
return: void
variants: []
-description: null
+description: |
+ The cache lines covering the area are marked as invalid. A later
+ instruction fetch from the area will result in a load from memory.
enabled-by: true
index-entries: []
interface-type: function
@@ -26,12 +28,16 @@ links:
- role: constraint
uid: /constraint/directive-no-preempt
name: rtems_cache_invalidate_multiple_instruction_lines
-notes: null
+notes: |
+ In SMP configurations, on processors without instruction cache snooping, this
+ operation will invalidate the instruction cache lines on all processors.
params:
-- description: '%'
+- description: |
+ is the begin address of the memory area to invalidate.
dir: null
- name: addr
-- description: '%'
+ name: begin
+- description: |
+ is the size in bytes of the memory area to invalidate.
dir: null
name: size
return:
diff --git a/spec/rtems/cache/if/unfreeze-data.yml b/spec/rtems/cache/if/unfreeze-data.yml
index 461993c..f62ddd6 100644
--- a/spec/rtems/cache/if/unfreeze-data.yml
+++ b/spec/rtems/cache/if/unfreeze-data.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Unfreezes the data cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -17,7 +17,7 @@ interface-type: function
links:
- role: interface-placement
uid: header
-- role: interface-ingroup
+- role: interface-ingroup-hidden
uid: group
- role: constraint
uid: /constraint/directive-ctx-any
diff --git a/spec/rtems/cache/if/unfreeze-instruction.yml b/spec/rtems/cache/if/unfreeze-instruction.yml
index b49586b..f0d8a2f 100644
--- a/spec/rtems/cache/if/unfreeze-instruction.yml
+++ b/spec/rtems/cache/if/unfreeze-instruction.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Unfreezes the instruction cache.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -17,7 +17,7 @@ interface-type: function
links:
- role: interface-placement
uid: header
-- role: interface-ingroup
+- role: interface-ingroup-hidden
uid: group
- role: constraint
uid: /constraint/directive-ctx-any
More information about the vc
mailing list