add plugin_v2 (1a1a11a#230)

* add plugin_v2

* Update libCacheSim/cache/eviction/plugin_cache.c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* clean up

* Unify ON and OFF

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Percy <xhc_1007@163.com>

Author: 3 people

example/plugin_v2/CMakeLists.txt

@@ -0,0 +1,71 @@
+cmake_minimum_required(VERSION 3.12)
+
+# Set the project name
+project(plugin_lru_example)
+
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Enable position independent code for shared libraries
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Find required dependencies
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(GLIB REQUIRED glib-2.0)
+message(STATUS "GLIB library: ${GLIB_LIBRARIES}")
+message(STATUS "GLIB include: ${GLIB_INCLUDE_DIRS}")
+
+# Find libCacheSim
+find_library(LIBCACHESIM_LIBRARY
+    NAMES CacheSim libCacheSim
+    PATHS /usr/local/lib /usr/lib
+    DOC "libCacheSim unified library"
+)
+
+find_path(LIBCACHESIM_INCLUDE_DIR
+    NAMES libCacheSim.h
+    PATHS /usr/local/include /usr/include
+    DOC "libCacheSim include directory"
+)
+
+message(STATUS "libCacheSim library: ${LIBCACHESIM_LIBRARY}")
+message(STATUS "libCacheSim include: ${LIBCACHESIM_INCLUDE_DIR}")
+
+if(NOT LIBCACHESIM_LIBRARY OR NOT LIBCACHESIM_INCLUDE_DIR)
+    message(FATAL_ERROR "libCacheSim not found! Please install libCacheSim first.")
+endif()
+
+# Add the shared library target
+add_library(plugin_lru_hooks SHARED plugin_lru.cpp)
+
+# Set compiler flags
+target_compile_options(plugin_lru_hooks PRIVATE
+    -Wall -Wextra 
+    -Wno-unused-variable -Wno-unused-function -Wno-unused-parameter
+)
+target_include_directories(plugin_lru_hooks PRIVATE
+    ${GLIB_INCLUDE_DIRS}
+    ${LIBCACHESIM_INCLUDE_DIR}
+)
+# Link libraries
+target_link_libraries(plugin_lru_hooks
+    ${GLIB_LIBRARIES}
+    ${LIBCACHESIM_LIBRARY}
+)
+
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/test_hooks_plugin.c")
+    add_executable(test_hooks_plugin test_hooks_plugin.c)
+    target_include_directories(test_hooks_plugin PRIVATE
+        ${LIBCACHESIM_INCLUDE_DIR}
+        ${GLIB_INCLUDE_DIRS}
+    )
+    target_link_libraries(test_hooks_plugin
+        ${GLIB_LIBRARIES}
+        ${LIBCACHESIM_LIBRARY}
+        dl
+        m
+    )
+endif()

example/plugin_v2/README.md

@@ -0,0 +1,87 @@
+# Plugin V2 Example - LRU Cache with Hooks
+
+This example demonstrates how to create a plugin for libCacheSim using the v2 hook-based plugin system. The plugin implements a standalone LRU (Least Recently Used) cache algorithm that integrates with libCacheSim's plugin_cache.c framework.
+
+## Files
+
+- `plugin_lru.cpp` - The main LRU cache plugin implementation using hooks
+- `test_hooks_plugin.c` - Comprehensive test program for the plugin
+- `CMakeLists.txt` - Build configuration for creating the shared library
+
+## Building
+
+To compile the plugin into a shared library:
+
+```bash
+mkdir build
+cd build
+cmake ..
+make
+```
+
+This will create:
+- `libplugin_lru_hooks.so` - Shared library
+- `test_hooks_plugin` - Test executable for validation
+
+## Plugin Architecture
+
+The plugin implements a standalone LRU cache using C++ with a C interface for compatibility with libCacheSim. It uses:
+
+- **StandaloneLRU Class**: C++ implementation with doubly-linked list and hash map
+- **Hook Functions**: C interface functions that plugin_cache.c calls
+
+### Hook Functions
+
+The plugin implements these required hook functions:
+
+- `cache_init_hook()` - Initialize the LRU cache data structure
+- `cache_hit_hook()` - Handle cache hits (move object to head of LRU list)
+- `cache_miss_hook()` - Handle cache misses (insert new object)
+- `cache_eviction_hook()` - Evict least recently used object and return its ID
+- `cache_remove_hook()` - Remove specific object from cache
+
+## Usage
+
+### With cachesim Binary
+
+```bash
+# Run cachesim with the plugin
+./bin/cachesim ../data/cloudPhysicsIO.vscsi vscsi lru,pluginCache 0.01,0.1 \
+  -e "plugin_path=/path/to/libCacheSim/example/plugin_v2/build/libplugin_lru_hooks.so"
+```
+
+### Testing the Plugin
+
+Run the included test to verify plugin functionality:
+
+```bash
+cd build
+./test_hooks_plugin
+```
+
+The test compares the plugin LRU implementation against libCacheSim's built-in LRU to ensure identical behavior.
+
+## Dependencies
+
+- **libCacheSim**: Headers and libraries from the main project
+- **CMake 3.12+**: Build system
+
+## Plugin Parameter Format
+
+When using the plugin with cachesim or other libCacheSim tools, use the format:
+```
+plugin_path=/full/path/to/libplugin_lru_hooks.so
+```
+
+## Implementation Notes
+
+- The plugin uses C++ internally but exports C functions for compatibility
+- Memory management is handled automatically by the StandaloneLRU destructor
+- The implementation maintains the same LRU semantics as libCacheSim's built-in LRU
+- Thread safety is not implemented - suitable for single-threaded use cases
+
+## Troubleshooting
+
+- Ensure the plugin path uses the `plugin_path=` prefix format
+- Verify all dependencies are available (check with `ldd libplugin_lru_hooks.so`)
+- Use absolute paths when specifying the plugin location

example/plugin_v2/plugin_lru.cpp

@@ -0,0 +1,137 @@
+//
+// LRU Cache Plugin with Hooks for libCacheSim plugin_cache.c
+// This implements the hook-based plugin system that plugin_cache.c expects
+//
+
+#include <glib.h>
+#include <libCacheSim.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#include <unordered_map>
+
+class StandaloneLRU {
+ public:
+  struct Node {
+    obj_id_t obj_id;
+    uint64_t obj_size;
+    Node *prev;
+    Node *next;
+
+    Node(obj_id_t k = 0, uint64_t obj_size = 0)
+        : obj_id(k), obj_size(obj_size), prev(nullptr), next(nullptr) {}
+  };
+
+  std::unordered_map<obj_id_t, Node *> cache_map;
+  Node *head;
+  Node *tail;
+
+  StandaloneLRU() {
+    head = new Node();
+    tail = new Node();
+    head->next = tail;
+    tail->prev = head;
+  }
+
+  ~StandaloneLRU() {
+    while (head) {
+      Node *temp = head;
+      head = head->next;
+      delete temp;
+    }
+  }
+
+  void add_to_head(Node *node) {
+    node->prev = head;
+    node->next = head->next;
+    head->next->prev = node;
+    head->next = node;
+  }
+
+  void remove_node(Node *node) {
+    node->prev->next = node->next;
+    node->next->prev = node->prev;
+  }
+
+  Node *remove_tail() {
+    Node *last_node = tail->prev;
+    remove_node(last_node);
+    return last_node;
+  }
+
+  void move_to_head(Node *node) {
+    remove_node(node);
+    add_to_head(node);
+  }
+
+  void cache_hit(obj_id_t obj_id) {
+    Node *node = cache_map[obj_id];
+    move_to_head(node);
+  }
+
+  void cache_miss(obj_id_t obj_id, uint64_t obj_size) {
+    Node *new_node = new Node(obj_id, obj_size);
+    cache_map[obj_id] = new_node;
+    add_to_head(new_node);
+  }
+
+  obj_id_t cache_eviction() {
+    Node *node = remove_tail();
+    obj_id_t evicted_id = node->obj_id;
+    cache_map.erase(evicted_id);
+    delete node;
+    return evicted_id;
+  }
+
+  void cache_remove(obj_id_t obj_id) {
+    auto it = cache_map.find(obj_id);
+    if (it == cache_map.end()) {
+      return;
+    }
+    Node *node = it->second;
+    remove_node(node);
+    cache_map.erase(it);
+    delete node;
+  }
+};
+
+// C interface for the plugin hooks
+extern "C" {
+
+// implement the cache init hook
+void *cache_init_hook(const common_cache_params_t ccache_params) {
+  // initialize the LRU cache
+  StandaloneLRU *lru_cache = new StandaloneLRU();
+  return lru_cache;
+}
+
+// implement the cache hit hook
+void cache_hit_hook(void *data, const request_t *req) {
+  // move object to the head of the list
+  StandaloneLRU *lru_cache = (StandaloneLRU *)data;
+  lru_cache->cache_hit(req->obj_id);
+}
+
+// implement the cache miss hook
+void cache_miss_hook(void *data, const request_t *req) {
+  // insert object into the cache
+  StandaloneLRU *lru_cache = (StandaloneLRU *)data;
+  lru_cache->cache_miss(req->obj_id, req->obj_size);
+}
+
+// implement the cache eviction hook
+obj_id_t cache_eviction_hook(void *data, const request_t *req) {
+  // evict the least recently used object
+  StandaloneLRU *lru_cache = (StandaloneLRU *)data;
+  return lru_cache->cache_eviction();
+}
+
+// implement the cache remove hook
+void cache_remove_hook(void *data, const obj_id_t obj_id) {
+  // remove object from the cache
+  StandaloneLRU *lru_cache = (StandaloneLRU *)data;
+  lru_cache->cache_remove(obj_id);
+}
+
+}  // extern "C"

example/plugin_v2/test_hooks_plugin.c

@@ -0,0 +1,57 @@
+#include <assert.h>
+#include <libCacheSim.h>
+#include <libgen.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "libCacheSim/cache.h"
+#include "libCacheSim/evictionAlgo.h"
+
+static const char *plugin_lib_name = "libplugin_lru_hooks.so";
+
+int main(int argc, char *argv[]) {
+  common_cache_params_t cache_params = {
+      .cache_size = 1000,  // Small cache for easy testing
+      .default_ttl = 0,
+      .hashpower = 16,
+      .consider_obj_metadata = false,
+  };
+
+  // create a plugin LRU cache
+  char *curr_bin_path = strdup(argv[0]);
+  char *curr_dir = dirname(curr_bin_path);
+  char *plugin_path = malloc(strlen(curr_dir) + strlen(plugin_lib_name) + 20);
+  sprintf(plugin_path, "plugin_path=%s/%s", curr_dir, plugin_lib_name);
+  printf("plugin_path: %s\n", plugin_path);
+  cache_t *plugin_cache = pluginCache_init(cache_params, plugin_path);
+  assert(plugin_cache != NULL);
+
+  request_t *req = new_request();
+  assert(req != NULL);
+
+  // create a LRU cache
+  cache_t *lru_cache = LRU_init(cache_params, NULL);
+  assert(lru_cache != NULL);
+
+  // generate a 1000 random requests and compare the result of the plugin LRU
+  // cache and the default LRU cache
+  for (int i = 0; i < 1000; i++) {
+    req->obj_id = rand() % 1000;
+    req->obj_size = rand() % 10;
+    req->clock_time = i;
+
+    bool hit1 = plugin_cache->get(plugin_cache, req);
+    bool hit2 = lru_cache->get(lru_cache, req);
+    assert(hit1 == hit2);
+  }
+
+  // free the request
+  free_request(req);
+  plugin_cache->cache_free(plugin_cache);
+  lru_cache->cache_free(lru_cache);
+  printf("Plugin LRU cache and LRU cache are the same\n\n");
+  return 0;
+}

libCacheSim/bin/cachesim/cache_init.h

@@ -56,6 +56,8 @@ static inline cache_t *create_cache(const char *trace_path,
       {"lru", LRU_init},
       {"lru-prob", LRU_Prob_init},
       {"nop", nop_init},
+      // plugin cache that allows user to implement custom cache
+      {"pluginCache", pluginCache_init},
       {"qdlp", QDLP_init},
       {"random", Random_init},
       {"RandomLRU", RandomLRU_init},

libCacheSim/bin/cachesim/cli_parser.c

@@ -117,7 +117,7 @@ static error_t parse_opt(int key, char *arg, struct argp_state *state) {
     case OPTION_EVICTION_PARAMS:
       arguments->eviction_params = strdup(arg);
       replace_char(arguments->eviction_params, ';', ',');
-      replace_char(arguments->eviction_params, '_', '-');
+      // replace_char(arguments->eviction_params, '_', '-');
       break;
     case OPTION_ADMISSION_ALGO:
       arguments->admission_algo = arg;
@@ -128,12 +128,12 @@ static error_t parse_opt(int key, char *arg, struct argp_state *state) {
     case OPTION_ADMISSION_PARAMS:
       arguments->admission_params = strdup(arg);
       replace_char(arguments->admission_params, ';', ',');
-      replace_char(arguments->admission_params, '_', '-');
+      // replace_char(arguments->admission_params, '_', '-');
       break;
     case OPTION_PREFETCH_PARAMS:
       arguments->prefetch_params = strdup(arg);
       replace_char(arguments->prefetch_params, ';', ',');
-      replace_char(arguments->prefetch_params, '_', '-');
+      // replace_char(arguments->prefetch_params, '_', '-');
       break;
     case OPTION_OUTPUT_PATH:
       strncpy(arguments->ofilepath, arg, OFILEPATH_LEN - 1);

libCacheSim/cache/CMakeLists.txt

@@ -45,6 +45,7 @@ set(eviction_sources_c
         eviction/LRUv0.c         # an inefficient version but easier to understand
         eviction/MRU.c
         eviction/nop.c
+        eviction/plugin_cache.c  # plugin cache that allows user to implement custom cache
         eviction/QDLP.c
         eviction/Random.c
         eviction/RandomLRU.c