From 02cbe5c7f3a9dea72e50ed3e9c5353b3462aa292 Mon Sep 17 00:00:00 2001
From: Marc Emery <marc.emery@amnis.ch>
Date: Mon, 4 May 2026 15:30:09 +0200
Subject: [PATCH] Improve Plru doc and add it the the index

---
 source/SpinalHDL/Libraries/Misc/Plru.rst  | 47 ++++++++++++++---------
 source/SpinalHDL/Libraries/Misc/index.rst |  1 +
 2 files changed, 30 insertions(+), 18 deletions(-)

diff --git a/source/SpinalHDL/Libraries/Misc/Plru.rst b/source/SpinalHDL/Libraries/Misc/Plru.rst
index b83a4aedcb4..09e6f3103e2 100644
--- a/source/SpinalHDL/Libraries/Misc/Plru.rst
+++ b/source/SpinalHDL/Libraries/Misc/Plru.rst
@@ -6,38 +6,49 @@ Plru
 
 Introduction
 ------------
-- Pseudo least recently used combinatorial logic
-- io.context.state need to be handled externally.
-- When you want to specify a access to a entry, you can use the io.update interface to get the new state value.
-- plru.io.evict.id tells you the id of the next block to be evicted
-- plru.io.update.id lets you update what you recently used
 
+The `Pseudo Least Recently Used <https://en.wikipedia.org/wiki/Pseudo-LRU>`_
+algorithm can be used for example in cache to select efficiently a line
+for eviction.
 
-PLRU Code
+It is used for example `in the VexiiRiscV core <https://github.com/SpinalHDL/VexiiRiscv/blob/3cff1cc2411ca97e6ee9ef64414ef274d30371e1/src/main/scala/vexiiriscv/execute/lsu/LsuL1Plugin.scala#L830>`_
+or in `spinal.lib.bus.tilelink.coherent.Cache <https://github.com/SpinalHDL/SpinalHDL/blob/78f29dc66110fc099a777992b6daa2f803ab445e/lib/src/main/scala/spinal/lib/bus/tilelink/coherent/Cache.scala#L1026>`_.
+
+- ``io.context.state`` need to be handled externally.
+- When you want to specify a access to a entry, you can use the ``io.update``
+  interface to get the new state value.
+- ``plru.io.evict.id`` tells you the id of the next block to be evicted
+- ``plru.io.update.id`` lets you update what you recently used
+
+
+PLRU Code:
 
 .. code-block:: scala
 
-   val io = new Bundle{
-    val context = new Bundle{
-      //user -> plru, specify the current state
+   val io = new Bundle {
+    val context = new Bundle {
+      // user -> plru, specify the current state
       val state = Plru.State(entries) 
-      //user -> plru, allow to specify prefered entries to remove. each bit set mean : "i would prefer that way to not to be selected by PLRU"
+      // user -> plru, allow to specify preferred entries to remove. Each bit
+      // set mean : "i would prefer that way to not to be selected by PLRU"
       val valids = withEntriesValid generate Bits(entries bits) 
     }
-    val evict = new Bundle{
-      //PLRU -> user, Tells you the least recently used entry for the given context provided above
+    val evict = new Bundle {
+      // PLRU -> user, Tells you the least recently used entry for the
+      // given context provided above
       val id =  UInt(log2Up(entries) bits)
     }
-    val update = new Bundle{
-      // user -> PLRU specify which entry the user want to mark as most recently used
+    val update = new Bundle {
+      // user -> PLRU specify which entry the user want to mark as
+      // most recently used
       val id = UInt(log2Up(entries) bits)
-     // PLRU -> user specfy what should then be the new value of the PLRU status 
+      // PLRU -> user specfy what should then be the new value of the PLRU status 
       val state = Plru.State(entries)
     }
   }
 
 
-Example usage in a cache 
+Example usage in a cache:
 
 .. code-block:: scala
 
@@ -51,13 +62,13 @@ Example usage in a cache
    }
 
 
-Get the ID of the way to evict from
+Get the ID of the way to evict from:
 
 .. code-block:: scala
 
    val replacedWay = plru.io.evict.id
 
-Update recently used way
+Update recently used way:
 
 .. code-block:: scala
 
diff --git a/source/SpinalHDL/Libraries/Misc/index.rst b/source/SpinalHDL/Libraries/Misc/index.rst
index 7784094f4ab..aa7b72533d1 100644
--- a/source/SpinalHDL/Libraries/Misc/index.rst
+++ b/source/SpinalHDL/Libraries/Misc/index.rst
@@ -7,3 +7,4 @@ Misc
 
    */*
    service_plugin
+   Plru