339 lines
8.5 KiB
C
339 lines
8.5 KiB
C
/*
|
|
* Copyright(c) 2012-2018 Intel Corporation
|
|
* SPDX-License-Identifier: BSD-3-Clause-Clear
|
|
*/
|
|
|
|
#ifndef __OCF_CTX_H__
|
|
#define __OCF_CTX_H__
|
|
|
|
/**
|
|
* @file
|
|
* @brief OCF library context API
|
|
*/
|
|
|
|
#include "ocf_types.h"
|
|
#include "ocf_data_obj.h"
|
|
#include "ocf_logger.h"
|
|
|
|
/**
|
|
* @brief Seeking start position in environment data buffer
|
|
*/
|
|
typedef enum {
|
|
ctx_data_seek_begin,
|
|
/*!< Seeking from the beginning of environment data buffer */
|
|
ctx_data_seek_current,
|
|
/*!< Seeking from current position in environment data buffer */
|
|
} ctx_data_seek_t;
|
|
|
|
/**
|
|
* @brief Context data representation ops
|
|
*/
|
|
struct ocf_data_ops {
|
|
/**
|
|
* @brief Allocate contest data buffer
|
|
*
|
|
* @param[in] pages The size of data buffer in pages
|
|
*
|
|
* @return Context data buffer
|
|
*/
|
|
ctx_data_t *(*alloc)(uint32_t pages);
|
|
|
|
/**
|
|
* @brief Free context data buffer
|
|
*
|
|
* @param[in] data Contex data buffer which shall be freed
|
|
*/
|
|
void (*free)(ctx_data_t *data);
|
|
|
|
/**
|
|
* @brief Lock context data buffer to disable swap-out
|
|
*
|
|
* @param[in] data Contex data buffer which shall be locked
|
|
*
|
|
* @retval 0 Memory locked successfully
|
|
* @retval Non-zero Memory locking failure
|
|
*/
|
|
int (*mlock)(ctx_data_t *data);
|
|
|
|
/**
|
|
* @brief Unlock context data buffer
|
|
*
|
|
* @param[in] data Contex data buffer which shall be unlocked
|
|
*/
|
|
void (*munlock)(ctx_data_t *data);
|
|
|
|
/**
|
|
* @brief Read from environment data buffer into raw data buffer
|
|
*
|
|
* @param[in,out] dst Destination raw memory buffer
|
|
* @param[in] src Source context data buffer
|
|
* @param[in] size Number of bytes to be read
|
|
*
|
|
* @return Number of read bytes
|
|
*/
|
|
uint32_t (*read)(void *dst, ctx_data_t *src, uint32_t size);
|
|
|
|
/**
|
|
* @brief Write raw data buffer into context data buffer
|
|
*
|
|
* @param[in,out] dst Destination context data buffer
|
|
* @param[in] src Source raw memory buffer
|
|
* @param[in] size Number of bytes to be written
|
|
*
|
|
* @return Number of written bytes
|
|
*/
|
|
uint32_t (*write)(ctx_data_t *dst, const void *src, uint32_t size);
|
|
|
|
/**
|
|
* @brief Zero context data buffer
|
|
*
|
|
* @param[in,out] dst Destination context data buffer to be zeroed
|
|
* @param[in] size Number of bytes to be zeroed
|
|
*
|
|
* @return Number of zeroed bytes
|
|
*/
|
|
uint32_t (*zero)(ctx_data_t *dst, uint32_t size);
|
|
|
|
/**
|
|
* @brief Seek read/write head in context data buffer for specified
|
|
* offset
|
|
*
|
|
* @param[in,out] dst Destination context data buffer to be seek
|
|
* @param[in] seek Seek beginning offset
|
|
* @param[in] size Number of bytes to be seek
|
|
*
|
|
* @return Number of seek bytes
|
|
*/
|
|
uint32_t (*seek)(ctx_data_t *dst, ctx_data_seek_t seek, uint32_t size);
|
|
|
|
/**
|
|
* @brief Copy context data buffer content
|
|
*
|
|
* @param[in,out] dst Destination context data buffer
|
|
* @param[in] src Source context data buffer
|
|
* @param[in] to Starting offset in destination buffer
|
|
* @param[in] from Starting offset in source buffer
|
|
* @param[in] bytes Number of bytes to be copied
|
|
*
|
|
* @return Number of bytes copied
|
|
*/
|
|
uint64_t (*copy)(ctx_data_t *dst, ctx_data_t *src,
|
|
uint64_t to, uint64_t from, uint64_t bytes);
|
|
|
|
/**
|
|
* @brief Erase content of data buffer
|
|
*
|
|
* @param[in] dst Contex data buffer which shall be erased
|
|
*/
|
|
void (*secure_erase)(ctx_data_t *dst);
|
|
};
|
|
|
|
/**
|
|
* @brief I/O queue operations
|
|
*/
|
|
struct ocf_queue_ops {
|
|
/**
|
|
* @brief Initialize I/O queue.
|
|
*
|
|
* This function should create worker, thread or any other queue
|
|
* processing related stuff specific to given environment.
|
|
*
|
|
* @param[in] q I/O queue to be initialized
|
|
*
|
|
* @retval 0 I/O queue has been initializaed successfully
|
|
* @retval Non-zero I/O queue initialization failure
|
|
*/
|
|
int (*init)(ocf_queue_t q);
|
|
|
|
/**
|
|
* @brief Kick I/O queue processing
|
|
*
|
|
* This function should inform worker, thread or any other queue
|
|
* processing mechanism, that there are new requests in queue to
|
|
* be processed. Processing requests inside current call is not allowed.
|
|
*
|
|
* @param[in] q I/O queue to be kicked
|
|
*/
|
|
void (*kick)(ocf_queue_t q);
|
|
|
|
/**
|
|
* @brief Kick I/O queue processing
|
|
*
|
|
* This function should inform worker, thread or any other queue
|
|
* processing mechanism, that there are new requests in queue to
|
|
* be processed. Kick function is allowed to process requests in current
|
|
* call
|
|
*
|
|
* @param[in] q I/O queue to be kicked
|
|
*/
|
|
void (*kick_sync)(ocf_queue_t q);
|
|
|
|
/**
|
|
* @brief Stop I/O queue
|
|
*
|
|
* @param[in] q I/O queue beeing stopped
|
|
*/
|
|
void (*stop)(ocf_queue_t q);
|
|
};
|
|
|
|
/**
|
|
* @brief Cleaner operations
|
|
*/
|
|
struct ocf_cleaner_ops {
|
|
/**
|
|
* @brief Initialize cleaner.
|
|
*
|
|
* This function should create worker, thread, timer or any other
|
|
* mechanism responsible for calling cleaner routine.
|
|
*
|
|
* @param[in] c Descriptor of cleaner to be initialized
|
|
*
|
|
* @retval 0 Cleaner has been initializaed successfully
|
|
* @retval Non-zero Cleaner initialization failure
|
|
*/
|
|
int (*init)(ocf_cleaner_t c);
|
|
|
|
/**
|
|
* @brief Stop cleaner
|
|
*
|
|
* @param[in] c Descriptor of cleaner beeing stopped
|
|
*/
|
|
void (*stop)(ocf_cleaner_t c);
|
|
};
|
|
|
|
/**
|
|
* @brief Metadata updater operations
|
|
*/
|
|
struct ocf_metadata_updater_ops {
|
|
/**
|
|
* @brief Initialize metadata updater.
|
|
*
|
|
* This function should create worker, thread, timer or any other
|
|
* mechanism responsible for calling metadata updater routine.
|
|
*
|
|
* @param[in] mu Handle to metadata updater to be initialized
|
|
*
|
|
* @retval 0 Metadata updater has been initializaed successfully
|
|
* @retval Non-zero I/O queue initialization failure
|
|
*/
|
|
int (*init)(ocf_metadata_updater_t mu);
|
|
|
|
/**
|
|
* @brief Kick metadata updater processing
|
|
*
|
|
* This function should inform worker, thread or any other mechanism,
|
|
* that there are new metadata requests to be processed.
|
|
*
|
|
* @param[in] mu Metadata updater to be kicked
|
|
*/
|
|
void (*kick)(ocf_metadata_updater_t mu);
|
|
|
|
/**
|
|
* @brief Stop metadata updater
|
|
*
|
|
* @param[in] mu Metadata updater beeing stopped
|
|
*/
|
|
void (*stop)(ocf_metadata_updater_t mu);
|
|
};
|
|
|
|
/**
|
|
* @brief OCF context specific operation
|
|
*/
|
|
struct ocf_ctx_ops {
|
|
/**
|
|
* @brief The name of the environment which provides platform
|
|
* interface for cache engine
|
|
*/
|
|
const char *name;
|
|
|
|
struct ocf_data_ops data;
|
|
struct ocf_queue_ops queue;
|
|
struct ocf_cleaner_ops cleaner;
|
|
struct ocf_metadata_updater_ops metadata_updater;
|
|
struct ocf_logger_ops logger;
|
|
};
|
|
|
|
/**
|
|
* @brief Register data object interface
|
|
*
|
|
* @note Type of data object operations is unique and cannot be repeated.
|
|
*
|
|
* @param[in] ctx OCF context
|
|
* @param[in] properties Reference to data object properties
|
|
* @param[in] type_id Type id of data object operations
|
|
*
|
|
* @retval 0 Data object operations registered successfully
|
|
* @retval Non-zero Data object registration failure
|
|
*/
|
|
int ocf_ctx_register_data_obj_type(ocf_ctx_t ctx, uint8_t type_id,
|
|
const struct ocf_data_obj_properties *properties);
|
|
|
|
/**
|
|
* @brief Unregister data object interface
|
|
*
|
|
* @param[in] ctx OCF context
|
|
* @param[in] type_id Type id of data object operations
|
|
*/
|
|
void ocf_ctx_unregister_data_obj_type(ocf_ctx_t ctx, uint8_t type_id);
|
|
|
|
/**
|
|
* @brief Get data object type operations by type id
|
|
*
|
|
* @param[in] ctx OCF context
|
|
* @param[in] type_id Type id of data object operations which were registered
|
|
*
|
|
* @return Data object type
|
|
* @retval NULL When data object operations were not registered
|
|
* for requested type
|
|
*/
|
|
ocf_data_obj_type_t ocf_ctx_get_data_obj_type(ocf_ctx_t ctx, uint8_t type_id);
|
|
|
|
/**
|
|
* @brief Get data object type id by type
|
|
*
|
|
* @param[in] ctx OCF context
|
|
* @param[in] type Type of data object operations which were registered
|
|
*
|
|
* @return Data object type id
|
|
* @retval -1 When data object operations were not registered
|
|
* for requested type
|
|
*/
|
|
int ocf_ctx_get_data_obj_type_id(ocf_ctx_t ctx, ocf_data_obj_type_t type);
|
|
|
|
/**
|
|
* @brief Create data object of given type
|
|
*
|
|
* @param[in] ctx handle to object designating ocf context
|
|
* @param[out] obj data object handle
|
|
* @param[in] uuid OCF data object UUID
|
|
* @param[in] type_id cache/core object type id
|
|
*
|
|
* @return Zero when success, othewise en error
|
|
*/
|
|
|
|
int ocf_ctx_data_obj_create(ocf_ctx_t ctx, ocf_data_obj_t *obj,
|
|
struct ocf_data_obj_uuid *uuid, uint8_t type_id);
|
|
|
|
/**
|
|
* @brief Initialize OCF context
|
|
*
|
|
* @param[out] ctx OCF context
|
|
* @param[in] ops OCF context operations
|
|
*
|
|
* @return Zero when success, otherwise an error
|
|
*/
|
|
int ocf_ctx_init(ocf_ctx_t *ctx, const struct ocf_ctx_ops *ops);
|
|
|
|
/**
|
|
* @brief De-Initialize OCF context
|
|
*
|
|
* @param[in] ctx OCF context
|
|
*
|
|
* @note Precondition is stopping all cache instances
|
|
*
|
|
* @return Zero when success, otherwise an error
|
|
*/
|
|
int ocf_ctx_exit(ocf_ctx_t ctx);
|
|
|
|
#endif /* __OCF_CTX_H__ */
|