From 80b3141de4f364b1f05adba199563fca01717fc7 Mon Sep 17 00:00:00 2001
From: Giovanni Di Sirio <gdisirio@gmail.com>
Date: Fri, 23 Aug 2019 08:04:00 +0000
Subject: [PATCH] Added module description.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@12952 27425a3e-05d8-49a3-a47f-9c15f0e5edd8
---
 os/oslib/include/chobjcaches.h |  5 +++--
 os/oslib/src/chobjcaches.c     | 32 +++++++++++++++++++++++---------
 2 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/os/oslib/include/chobjcaches.h b/os/oslib/include/chobjcaches.h
index 67f5e9527..9b01616e6 100644
--- a/os/oslib/include/chobjcaches.h
+++ b/os/oslib/include/chobjcaches.h
@@ -39,8 +39,9 @@
  * @{
  */
 #define OC_FLAG_INVALID                     0x00000001U
-#define OC_FLAG_CACHEHIT                    0x00000002U
-#define OC_FLAG_ERROR                       0x00000004U
+#define OC_FLAG_INLRU                       0x00000002U
+#define OC_FLAG_CACHEHIT                    0x00000004U
+#define OC_FLAG_ERROR                       0x00000008U
 /** @} */
 
 /**
diff --git a/os/oslib/src/chobjcaches.c b/os/oslib/src/chobjcaches.c
index b6afb491d..4551ec892 100644
--- a/os/oslib/src/chobjcaches.c
+++ b/os/oslib/src/chobjcaches.c
@@ -20,16 +20,30 @@
 /**
  * @file    chobjcaches.c
  * @brief   Objects Caches code.
- * @details Byte pipes.
+ * @details Objects caches.
  *          <h2>Operation mode</h2>
- *          A pipe is an asynchronous communication mechanism.<br>
- *          Operations defined for mailboxes:
- *          - <b>Write</b>: Writes a buffer of data in the pipe in FIFO order.
- *          - <b>Read</b>: A buffer of data is read from the read and removed.
- *          - <b>Reset</b>: The pipe is emptied and all the stored data
- *            is lost.
+ *          An object cache allows to retrieve and release objects from a
+ *          slow media, for example a disk or flash.<br>
+ *          The most recently used objects are kept in a series of RAM
+ *          buffers making access faster. Objects are identified by a
+ *          pair <group, key> which could be mapped, for example, to a
+ *          disk drive identifier and sector identifier.<br>
+ *          Read and write operations are performed using externally-supplied
+ *          functions, the cache is device-agnostic.<br>
+ *          The cache uses internally an hash table, the size of the table
+ *          should be dimensioned to minimize the risk of hash collisions,
+ *          a factor of two is usually acceptable, it depends on the specific
+ *          application requirements.<br>
+ *          Operations defined for caches:
+ *          - <b>Get Object</b>: Retrieves an object from cache, if not
+ *            present then an empty buffer is returned.
+ *          - <b>Read Object</b>: Retrieves an object from cache, if not
+ *            present a buffer is allocated and the object is read from the
+ *            media.
+ *          - <b>Release Object</b>: Releases an object to the cache handling
+ *            the media update, if required.
  *          .
- * @pre     In order to use the pipes APIs the @p CH_CFG_USE_PIPES
+ * @pre     In order to use the pipes APIs the @p CH_CFG_USE_OBJ_CACHES
  *          option must be enabled in @p chconf.h.
  * @note    Compatible with RT and NIL.
  *
@@ -151,7 +165,7 @@ void chCacheObjectInit(objects_cache_t *ocp,
     LRU_INSERT_HEAD(ocp, objp);
     objp->obj_group = OC_NO_GROUP;
     objp->obj_key   = 0U;
-    objp->obj_flags = OC_FLAG_INVALID;
+    objp->obj_flags = OC_FLAG_INLRU | OC_FLAG_INVALID;
     objp->data      = NULL;
   }
 }