cache: Add documentation

To disambiguate the Kconfig options available to the user.

Signed-off-by: Carlo Caione <ccaione@baylibre.com>

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

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