ceph/src/spdk/ocf/src/concurrency/ocf_cache_concurrency.h

   1 /*
   2  * Copyright(c) 2012-2018 Intel Corporation
   3  * SPDX-License-Identifier: BSD-3-Clause-Clear
   4  */
   5
   6 #ifndef OCF_CACHE_CONCURRENCY_H_
   7 #define OCF_CACHE_CONCURRENCY_H_
   8
   9 /**
  10  * @file utils_req.h
  11  * @brief OCF cache concurrency module
  12  */
  13
  14 /**
  15  * @brief OCF cache concurrency module handle
  16  */
  17 struct ocf_cache_concurrency;
  18
  19 /**
  20  * @brief Initialize OCF cache concurrency module
  21  *
  22  * @param cache - OCF cache instance
  23  * @return 0 - Initialization successful, otherwise ERROR
  24  */
  25 int ocf_cache_concurrency_init(struct ocf_cache *cache);
  26
  27 /**
  28  * @biref De-Initialize  OCF cache concurrency module
  29  *
  30  * @param cache - OCF cache instance
  31  */
  32 void ocf_cache_concurrency_deinit(struct ocf_cache *cache);
  33
  34 /**
  35  * @brief Get number of waiting (suspended) OCF requests in due to cache
  36  * overlapping
  37  *
  38  * @param cache - OCF cache instance
  39  *
  40  * @return Number of suspended OCF requests
  41  */
  42 uint32_t ocf_cache_concurrency_suspended_no(struct ocf_cache *cache);
  43
  44 /**
  45  * @brief Return memory footprint conusmed by cache concurrency module
  46  *
  47  * @param cache - OCF cache instance
  48  *
  49  * @return Memory footprint of cache concurrency module
  50  */
  51 size_t ocf_cache_concurrency_size_of(struct ocf_cache *cache);
  52
  53 /**
  54  * @brief Lock OCF request for WRITE access (Lock all cache lines in map info)
  55  *
  56  * @note req->resume callback has to be set
  57  *
  58  * @param req - OCF request
  59  *
  60  * @retval OCF_LOCK_ACQUIRED - OCF request has been locked and can be processed
  61  *
  62  * @retval OCF_LOCK_NOT_ACQUIRED - OCF request lock not acquired, request was
  63  * added into waiting list. When lock will be acquired req->resume be called
  64  */
  65 int ocf_req_trylock_wr(struct ocf_request *req);
  66
  67 /**
  68  * @brief Try complete lock of OCF request for WRITE access (Lock cache lines
  69  * that marked as invalid)
  70  *
  71  * @param req - OCF request
  72  *
  73  * @note If request not locked it will be added into waiting list
  74  *
  75  * @retval OCF_LOCK_ACQUIRED - OCF request has been locked and can be processed
  76  *
  77  * @retval OCF_LOCK_NOT_ACQUIRED - OCF request lock not acquired, request was
  78  * added into waiting list. When lock will be acquired req->resume be called
  79  */
  80 int ocf_req_retrylock_wr(struct ocf_request *req);
  81
  82 /**
  83  * @brief Lock OCF request for READ access (Lock all cache lines in map info)
  84  *
  85  * @note req->resume callback has to be set
  86  *
  87  * @param req - OCF request
  88  *
  89  * @retval OCF_LOCK_ACQUIRED - OCF request has been locked and can be processed
  90  *
  91  * @retval OCF_LOCK_NOT_ACQUIRED - OCF request lock not acquired, request was
  92  * added into waiting list. When lock will be acquired req->resume be called
  93  */
  94 int ocf_req_trylock_rd(struct ocf_request *req);
  95
  96 /**
  97  * @brief Unlock OCF request from WRITE access
  98  *
  99  * @param req - OCF request
 100  */
 101 void ocf_req_unlock_wr(struct ocf_request *req);
 102
 103 /**
 104  * @brief Unlock OCF request from READ access
 105  *
 106  * @param req - OCF request
 107  */
 108 void ocf_req_unlock_rd(struct ocf_request *req);
 109
 110 /**
 111  * @brief Unlock OCF request from READ or WRITE access
 112  *
 113  * @param req - OCF request
 114  */
 115 void ocf_req_unlock(struct ocf_request *req);
 116
 117 /**
 118  * @Check if cache line is used.
 119  *
 120  * Cache line is used when:
 121  * 1. It is locked for write or read access
 122  * or
 123  * 2. There is set locked bit in metadata
 124  *
 125  * @param cache - OCF cache instance
 126  * @param line - Cache line to be unlocked
 127  *
 128  * @retval true - cache line is used
 129  * @retval false - cache line is not used
 130  */
 131 bool ocf_cache_line_is_used(struct ocf_cache *cache,
 132                 ocf_cache_line_t line);
 133
 134 /**
 135  * @brief Check if for specified cache line there are waiters
 136  * on the waiting list
 137  *
 138  * @param cache - OCF cache instance
 139  * @param line - Cache line to be checked for waiters
 140  *
 141  * @retval true - there are waiters
 142  * @retval false - No waiters
 143  */
 144 bool ocf_cache_line_are_waiters(struct ocf_cache *cache,
 145                 ocf_cache_line_t line);
 146
 147 /**
 148  * @brief un_lock request map info entry from from WRITE or READ access.
 149  *
 150  * @param cache - OCF cache instance
 151  * @param req - OCF request
 152  * @param entry - request map entry number
 153  */
 154 void ocf_req_unlock_entry(struct ocf_cache *cache,
 155                 struct ocf_request *req, uint32_t entry);
 156
 157 /**
 158  * @brief Release cache line read lock
 159  *
 160  * @param cache - OCF cache instance
 161  * @param line - Cache line to be unlocked
 162  */
 163 void ocf_cache_line_unlock_rd(struct ocf_cache *cache, ocf_cache_line_t line);
 164
 165 /**
 166  * @brief Attempt to lock cache line for read
 167  *
 168  * @param cache - OCF cache instance
 169  * @param line - Cache line to be checked for waiters
 170  *
 171  * @retval true - read lock successfully acquired
 172  * @retval false - failed to acquire read lock
 173  */
 174 bool ocf_cache_line_try_lock_rd(struct ocf_cache *cache, ocf_cache_line_t line);
 175
 176 #endif /* OCF_CONCURRENCY_H_ */