ocf/inc/ocf_cache.h

/*
 * Copyright(c) 2012-2018 Intel Corporation
 * SPDX-License-Identifier: BSD-3-Clause-Clear
 */


#ifndef __OCF_CACHE_H__
#define __OCF_CACHE_H__

/**
 * @file
 * @brief OCF cache API
 */

#include "ocf_types.h"
#include "ocf_data_obj.h"
#include "ocf_ctx.h"
#include "ocf_def.h"

/**
 * @brief Cache info: configuration, status
 */
struct ocf_cache_info {
	bool attached;
		/*!< True if caching cache is attached to cache */

	uint8_t data_obj_type;
		/*!< Cache data object type */

	uint32_t size;
		/*!< Actual cache size (in cache lines) */

	/* Statistics of inactive cores */
	struct {
		uint32_t occupancy;
			/*!< Cache occupancy (in cache lines) */

		uint32_t dirty;
			/*!< Dirty blocks within cache (in cache lines) */
	} inactive;

	uint32_t occupancy;
		/*!< Actual cache occupancy (in cache lines) */

	uint32_t dirty;
		/*!< Dirty blocks within cache (in cache lines) */

	uint32_t dirty_initial;
		/*!< Dirty blocks within cache that where there when switching
		 * out of WB mode
		 */

	uint32_t dirty_for;
		/*!< How long there are dirty cache lines (in seconds) */

	ocf_cache_mode_t cache_mode;
		/*!< Current cache mode */

	/* Statistics of fallback Pass Through */
	struct {
		int error_counter;
			/*!< How many requests to cache failed because of IO error */

		bool status;
			/*!< Current cache mode is PT,
			  set as a result of reaching IO error threshold */
	} fallback_pt;

	uint8_t state;
		/*!< Cache state (running/flushing/stopping etc...) */

	ocf_eviction_t eviction_policy;
		/*!< Eviction policy selected */

	ocf_cleaning_t cleaning_policy;
		/*!< Cleaning policy selected (alru/nop) */

	ocf_cache_line_size_t cache_line_size;
		/*!< Cache line size in KiB */

	uint32_t flushed;
		/*!< Number of block flushed in ongoing flush operation */

	uint32_t core_count;
		/*!< Number of core devices associated with this cache */

	uint64_t metadata_footprint;
		/*!< Metadata memory footprint (in bytes) */

	uint32_t metadata_end_offset;
		/*!< LBA offset where metadata ends (in 4KiB blocks) */
};

/**
 * @brief Obtain data object from cache
 *
 * @param[in] cache Cache object
 *
 * @retval Data object, NULL if dettached.
 */
ocf_data_obj_t ocf_cache_get_data_object(ocf_cache_t cache);

/**
 * @brief Get ID of given cache object
 *
 * @param[in] cache Cache object
 *
 * @retval Cache ID
 */
ocf_cache_id_t ocf_cache_get_id(ocf_cache_t cache);

/**
 * @brief Get queue object associated with cache
 *
 * @param[in] cache Cache object
 * @param[in] id Queue id
 * @param[out] q Queue object
 *
 * @retval 0 Success
 * @retval Non-zero Fail
 */
int ocf_cache_get_queue(ocf_cache_t cache, unsigned id, ocf_queue_t *q);

/**
 * @brief Set name of given cache object
 *
 * @param[in] cache Cache object
 * @param[in] src Source of Cache name
 * @param[in] src_size Size of src
 *
 * @retval 0 Success
 * @retval Non-zero Fail
 */
int ocf_cache_set_name(ocf_cache_t cache, const char *src, size_t src_size);

/**
 * @brief Get name of given cache object
 *
 * @param[in] cache Cache object
 *
 * @retval Cache name
 */
const char *ocf_cache_get_name(ocf_cache_t cache);

/**
 * @brief Check is cache in incomplete state
 *
 * @param[in] cache Cache object
 *
 * @retval 1 Cache is in incomplete state
 * @retval 0 Cache is in complete state
 */
bool ocf_cache_is_incomplete(ocf_cache_t cache);

/**
 * @brief Check if caching device is attached
 *
 * @param[in] cache Cache object
 *
 * @retval 1 Caching device is attached
 * @retval 0 Caching device is detached
 */
bool ocf_cache_is_device_attached(ocf_cache_t cache);

/**
 * @brief Check if cache object is running
 *
 * @param[in] cache Cache object
 *
 * @retval 1 Caching device is being stopped
 * @retval 0 Caching device is being stopped
 */
bool ocf_cache_is_running(ocf_cache_t cache);

/**
 * @brief Get cache mode of given cache object
 *
 * @param[in] cache Cache object
 *
 * @retval Cache mode
 */
ocf_cache_mode_t ocf_cache_get_mode(ocf_cache_t cache);

/**
 * @brief Get cache line size of given cache object
 *
 * @param[in] cache Cache object
 *
 * @retval Cache line size
 */
ocf_cache_line_size_t ocf_cache_get_line_size(ocf_cache_t cache);

/**
 * @brief Convert bytes to cache lines
 *
 * @param[in] cache Cache object
 * @param[in] bytes Number of bytes
 *
 * @retval Cache lines count
 */
uint64_t ocf_cache_bytes_2_lines(ocf_cache_t cache, uint64_t bytes);

/**
 * @brief Get core count of given cache object
 *
 * @param[in] cache Cache object
 *
 * @retval Core count
 */
uint32_t ocf_cache_get_core_count(ocf_cache_t cache);

/**
 * @brief Get cache mode of given cache object
 *
 * @param[in] cache Cache object
 * @param[out] info Cache info structure
 *
 * @retval 0 Success
 * @retval Non-zero Fail
 */
int ocf_cache_get_info(ocf_cache_t cache, struct ocf_cache_info *info);

/**
 * @brief Get UUID of data object associated with cache
 *
 * @param[in] cache Cache object
 *
 * @retval Data object UUID, NULL if detached.
 */
const struct ocf_data_obj_uuid *ocf_cache_get_uuid(ocf_cache_t cache);

/**
 * @brief Get OCF context of given cache object
 *
 * @param[in] cache Cache object
 *
 * @retval OCF context
 */
ocf_ctx_t ocf_cache_get_ctx(ocf_cache_t cache);

/**
 * @brief Get data object type id of given cache object
 *
 * @param[in] cache Cache object
 *
 * @retval data object type id, -1 if device detached
 */
uint8_t ocf_cache_get_type_id(ocf_cache_t cache);

#endif /* __OCF_CACHE_H__ */