Skip to content

Commit 9aba132

Browse files
nashifkartben
nashif
authored and
kartben
committed
doc: cache: fix cache doc structure
Wrong levels and cache topic appearing in the wrong table of contents. Signed-off-by: Anas Nashif <[email protected]>
1 parent e04d828 commit 9aba132

File tree

2 files changed

+77
-67
lines changed

2 files changed

+77
-67
lines changed

‎doc/hardware/cache/config.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
.. _cache_config:
2+
3+
Cache Control Configuration
4+
###########################
5+
6+
This is a high-level guide to Zephyr's cache interface and Kconfig options related to
7+
cache controllers. See :ref:`cache_api` for API reference material.
8+
9+
Zephyr has different Kconfig options to control how the cache controller is
10+
implemented and controlled.
11+
12+
* :kconfig:option:`CONFIG_CPU_HAS_DCACHE` /
13+
:kconfig:option:`CONFIG_CPU_HAS_ICACHE`: these hidden options should be
14+
selected at SoC / platform level when the CPU actually supports a data or
15+
instruction cache. The cache controller can be in the core or can be an
16+
external cache controller for which a driver is provided.
17+
18+
These options have the goal to document an available hardware feature and
19+
should be set whether we plan to support and use the cache control in Zephyr
20+
or not.
21+
22+
* :kconfig:option:`CONFIG_DCACHE` / :kconfig:option:`CONFIG_ICACHE`: these
23+
options must be selected when support for data or instruction cache is
24+
present and working in zephyr. Note that if these options are disabled,
25+
caching may still be enabled depending on the hardware defaults.
26+
27+
All the code paths related to cache control must be conditionally enabled
28+
depending on these symbols. When the symbol is set the cache is considered
29+
enabled and used.
30+
31+
These symbols say nothing about the actual API interface exposed to the user.
32+
For example a platform using the data cache can enable the
33+
:kconfig:option:`CONFIG_DCACHE` symbol and use some HAL exported function in
34+
some platform-specific code to enable and manage the d-cache.
35+
36+
* :kconfig:option:`CONFIG_CACHE_MANAGEMENT`: this option must be selected when
37+
the cache operations are exposed to the user through a standard API (see
38+
:ref:`cache_api`).
39+
40+
When this option is enabled we assume that all the cache functions are
41+
implemented in the architectural code or in an external cache controller
42+
driver.
43+
44+
* :kconfig:option:`CONFIG_MEM_ATTR`: this option allows the user to
45+
specify (using :ref:`memory region attributes<mem_mgmt_api>`) a fixed region
46+
in memory that will have caching disabled once the kernel has initialized.
47+
48+
* :kconfig:option:`CONFIG_NOCACHE_MEMORY`: this option allows the user to
49+
specify individual global variables as uncached using ``__nocache``. This will
50+
instruct the linker to place any marked variables into a special ``nocache``
51+
region in memory and the MPU driver will configure that region as uncached.
52+
53+
* :kconfig:option:`CONFIG_ARCH_CACHE`/:kconfig:option:`CONFIG_EXTERNAL_CACHE`:
54+
mutually exclusive options for :kconfig:option:`CACHE_TYPE` used to define
55+
whether the cache operations are implemented at arch level or using an
56+
external cache controller with a provided driver.
57+
58+
* :kconfig:option:`CONFIG_ARCH_CACHE`: the cache API is implemented by the
59+
arch code
60+
61+
* :kconfig:option:`CONFIG_EXTERNAL_CACHE`: the cache API is implemented by a
62+
driver that supports the external cache controller. In this case the driver
63+
must be located as usual in the :file:`drivers/cache/` directory
64+
65+
.. _cache_api:
66+
67+
Cache API
68+
*********
69+
70+
.. doxygengroup:: cache_interface

‎doc/hardware/cache/index.rst‎

Lines changed: 7 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,10 @@
1-
.. _cache_config:
1+
.. _cache:
22

3-
Cache Control Configuration
4-
###########################
3+
Caching
4+
#######
55

6-
This is a high-level guide to Zephyr's cache interface and Kconfig options related to
7-
cache controllers. See :ref:`cache_api` for API reference material.
6+
.. toctree::
7+
:maxdepth: 1
88

9-
Zephyr has different Kconfig options to control how the cache controller is
10-
implemented and controlled.
11-
12-
* :kconfig:option:`CONFIG_CPU_HAS_DCACHE` /
13-
:kconfig:option:`CONFIG_CPU_HAS_ICACHE`: these hidden options should be
14-
selected at SoC / platform level when the CPU actually supports a data or
15-
instruction cache. The cache controller can be in the core or can be an
16-
external cache controller for which a driver is provided.
17-
18-
These options have the goal to document an available hardware feature and
19-
should be set whether we plan to support and use the cache control in Zephyr
20-
or not.
21-
22-
* :kconfig:option:`CONFIG_DCACHE` / :kconfig:option:`CONFIG_ICACHE`: these
23-
options must be selected when support for data or instruction cache is
24-
present and working in zephyr. Note that if these options are disabled,
25-
caching may still be enabled depending on the hardware defaults.
26-
27-
All the code paths related to cache control must be conditionally enabled
28-
depending on these symbols. When the symbol is set the cache is considered
29-
enabled and used.
30-
31-
These symbols say nothing about the actual API interface exposed to the user.
32-
For example a platform using the data cache can enable the
33-
:kconfig:option:`CONFIG_DCACHE` symbol and use some HAL exported function in
34-
some platform-specific code to enable and manage the d-cache.
35-
36-
* :kconfig:option:`CONFIG_CACHE_MANAGEMENT`: this option must be selected when
37-
the cache operations are exposed to the user through a standard API (see
38-
:ref:`cache_api`).
39-
40-
When this option is enabled we assume that all the cache functions are
41-
implemented in the architectural code or in an external cache controller
42-
driver.
43-
44-
* :kconfig:option:`CONFIG_MEM_ATTR`: this option allows the user to
45-
specify (using :ref:`memory region attributes<mem_mgmt_api>`) a fixed region
46-
in memory that will have caching disabled once the kernel has initialized.
47-
48-
* :kconfig:option:`CONFIG_NOCACHE_MEMORY`: this option allows the user to
49-
specify individual global variables as uncached using ``__nocache``. This will
50-
instruct the linker to place any marked variables into a special ``nocache``
51-
region in memory and the MPU driver will configure that region as uncached.
52-
53-
* :kconfig:option:`CONFIG_ARCH_CACHE`/:kconfig:option:`CONFIG_EXTERNAL_CACHE`:
54-
mutually exclusive options for :kconfig:option:`CACHE_TYPE` used to define
55-
whether the cache operations are implemented at arch level or using an
56-
external cache controller with a provided driver.
57-
58-
* :kconfig:option:`CONFIG_ARCH_CACHE`: the cache API is implemented by the
59-
arch code
60-
61-
* :kconfig:option:`CONFIG_EXTERNAL_CACHE`: the cache API is implemented by a
62-
driver that supports the external cache controller. In this case the driver
63-
must be located as usual in the :file:`drivers/cache/` directory
64-
65-
.. _cache_api:
66-
67-
Cache API
68-
#########
69-
70-
.. doxygengroup:: cache_interface
9+
config.rst
10+
guide.rst

0 commit comments

Comments
 (0)