There is some user confusion about which cache types to choose when which
is not helped by the lack of any central documentation providing an
overview of what's available. Provide a short overview in the API header to
try to help reduce this.

Signed-off-by: Mark Brown <broonie@kernel.org>
---
 include/linux/regmap.h | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/include/linux/regmap.h b/include/linux/regmap.h
index 122e38161acb..5b59423e786a 100644
--- a/include/linux/regmap.h
+++ b/include/linux/regmap.h
@@ -54,7 +54,14 @@ struct sdw_slave;
 #define REGMAP_UPSHIFT(s)	(-(s))
 #define REGMAP_DOWNSHIFT(s)	(s)
 
-/* An enum of all the supported cache types */
+/*
+ * The supported cache types, the default is no cache.  Any new caches
+ * should usually use the maple tree cache unless they specifically
+ * require that there are never any allocations at runtime and can't
+ * provide defaults in which case they should use the flat cache.  The
+ * rbtree cache *may* have some performance advantage for very low end
+ * systems that make heavy use of cache syncs but is mainly legacy.
+ */
 enum regcache_type {
 	REGCACHE_NONE,
 	REGCACHE_RBTREE,

---
base-commit: 98f7e32f20d28ec452afb208f9cffc08448a2652
change-id: 20240923-regcache-document-types-5ab0e3448b8b

Best regards,
-- 
Mark Brown <broonie@kernel.org>

On Tue, 24 Sep 2024 12:08:08 +0200, Mark Brown wrote:
> There is some user confusion about which cache types to choose when which
> is not helped by the lack of any central documentation providing an
> overview of what's available. Provide a short overview in the API header to
> try to help reduce this.
> 
> 

Applied to

   https://git.kernel.org/pub/scm/linux/kernel/git/broonie/regmap.git for-next

Thanks!

[1/1] regcache: Improve documentation of available cache types
      commit: caf78b0465053c23aa6211b9815dd5433766627d

All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying
to this mail.

Thanks,
Mark