From c464a962e1a040c8b7d8dda3cc57d81e2ec4f542 Mon Sep 17 00:00:00 2001 From: Carlo Caione Date: Mon, 12 Dec 2022 18:26:40 +0100 Subject: [PATCH] cache: Add documentation To disambiguate the Kconfig options available to the user. Signed-off-by: Carlo Caione --- doc/hardware/cache/index.rst | 59 ++++++++++++++++++++++++++++++++++++ doc/hardware/index.rst | 1 + 2 files changed, 60 insertions(+) create mode 100644 doc/hardware/cache/index.rst diff --git a/doc/hardware/cache/index.rst b/doc/hardware/cache/index.rst new file mode 100644 index 00000000000..7f5fd5045e0 --- /dev/null +++ b/doc/hardware/cache/index.rst @@ -0,0 +1,59 @@ +.. _cache-guide: + +Cache Interface +############### + +This is a high-level guide to cache interface and Kconfig options related to +cache controllers. See :ref:`cache_api` for API reference material. + +Zephyr has different Kconfig options to control how the cache controller is +implemented and controlled. + +* :kconfig:option:`CONFIG_CPU_HAS_DCACHE` / + :kconfig:option:`CONFIG_CPU_HAS_ICACHE`: these hidden options should be + selected at SoC / platform level when the CPU actually supports a data or + instruction cache. The cache controller can be in the core or can be an + external cache controller for which a driver is provided. + + These options have the goal to document an available feature and should be + set whether we plan to support and use the caches in Zephyr or not. + +* :kconfig:option:`CONFIG_DCACHE` / :kconfig:option:`CONFIG_ICACHE`: these + options must be selected when support for data or instruction cache is + present and working in zephyr. + + All the code paths related to cache control must be conditionally enabled + depending on these symbols. When the symbol is set the cache is considered + enabled and used. + + These symbols say nothing about the actual API interface exposed to the user. + For example a platform using the data cache can enable the + :kconfig:option:`CONFIG_DCACHE` symbol and use some HAL exported function in + some platform-specific code to enable and manage the d-cache. + +* :kconfig:option:`CONFIG_CACHE_MANAGEMENT`: this option must be selected when + the cache operations are exposed to the user through a standard API (see + :ref:`cache_api`). + + When this option is enabled we assume that all the cache functions are + implemented in the architectural code or in an external cache controller + driver. + +* :kconfig:option:`CONFIG_ARCH_CACHE`/:kconfig:option:`CONFIG_EXTERNAL_CACHE`: + mutually exclusive options for :kconfig:option:`CACHE_TYPE` used to define + whether the cache operations are implemented at arch level or using an + external cache controller with a provided driver. + + * :kconfig:option:`CONFIG_ARCH_CACHE`: the cache API is implemented by the + arch code + + * :kconfig:option:`CONFIG_EXTERNAL_CACHE`: the cache API is implemented by a + driver that supports the external cache controller. In this case the driver + must be located as usual in the :file:`drivers/cache/` directory + +.. _cache_api: + +Cache API +********* + +.. doxygengroup:: cache_interface diff --git a/doc/hardware/index.rst b/doc/hardware/index.rst index 8dceb73b92c..c0d1aaca833 100644 --- a/doc/hardware/index.rst +++ b/doc/hardware/index.rst @@ -7,6 +7,7 @@ Hardware Support :maxdepth: 1 arch/index.rst + cache/index.rst emulator/index.rst peripherals/index.rst pinctrl/index.rst