safestore.h revision fcf3ce441efd61da9bb2884968af01cb7c1452cc
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License (the "License").
* You may not use this file except in compliance with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/*
* Copyright 2008 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _SD_SAFESTORE_H
#define _SD_SAFESTORE_H
#ifdef __cplusplus
extern "C" {
#endif
#include <sys/nsc_thread.h>
#ifdef DS_DDICT
#endif
/* CSTYLED */
/**$
* token for a volume directory stream
*/
typedef struct ss_vdir_s {
} ss_vdir_t;
/* CSTYLED */
/**$
* token for a cache entry directory stream
*/
typedef struct ss_cdir_s {
/* CSTYLED */
/**$
* token for a volume
*/
typedef struct ss_vol_s {
}ss_vol_t;
/* CSTYLED */
/**$
* token for cache entry block and dirty bits
*/
typedef struct s_resource_s {
/* CSTYLED */
/**$
* token for a list of cache safestore resources
*/
typedef struct ss_resourcelist_s {
/* CSTYLED */
/**$
* cache entry directory stream type specifier
*
* @field ck_type specifies all cache entries, cache entries for volume, node
* @field ck_vol volume token if ck_type is CDIR_VOL
* @field ck_node node id if ck_type is node CDIR_NODE
*/
typedef struct ss_cdirkey_s {
union {
} cdk_u;
} ss_cdirkey_t;
/* centry directory stream types */
#define CDIR_ALL 0
#define CDIR_VOL 1
#define CDIR_NODE 2
/* BEGIN CSTYLED */
/**$
* exported cache entry info
*
* @field sc_cd the cache descriptor, associates this entry with a volume
* @field sc_fpos file position in cache blocks
* @field sc_dirty dirty bits, one for each fba in the cache block
* @field sc_flag flags
* @field sc_res safestore resource token for this cache entry
* @see ss_voldata_t{}
*/
typedef struct ss_centry_info_s {
int sc_cd; /* Cache descriptor */
int sc_dirty; /* Dirty mask */
int sc_flag; /* CC_PINNABLE | CC_PINNED */
/* END CSTYLED */
/* CSTYLED */
/**$
* volume directory stream type specifier
*
* @field vk_type specifies all volume entries, entries for volume, node
* @field vk_vol volume token if vk_type is VDIR_VOL
* @field vk_node node id if vk_type is node VDIR_NODE
*/
typedef struct ss_vdirkey_s {
union {
} cdk_u;
} ss_vdirkey_t;
/* volume directory stream types */
#define VDIR_ALL 0
#define VDIR_VOL 1
#define VDIR_NODE 2
/* CSTYLED */
/**$
* exported volume entry info
*
* @field sv_cd the cache descriptor
* @field sv_vol the safestore volume token for this volume
* @field sv_pinned volume has pinned blocks, holds node id
* @field sv_attached node which has attached this volume
* @field sv_volname path name
* @field sv_devidsz length of device id, the sv_devid
* @field sv_devid unique id for physical, i.e. non-volume-managed volumes
*/
typedef struct ss_voldata_s {
int sv_cd; /* NOTE may need dual node map info */
int sv_attached; /* Node which has device attached */
int sv_devidsz; /* unique dev id length */
} ss_voldata_t;
/* safestore media types */
/* CSTYLED */
/**%
* safestore in RAM, useful but not very safe
*/
#define SS_M_RAM 0x00000001
/* CSTYLED */
/**%
* safestore in NVRAM on a single node
*/
#define SS_M_NV_SINGLENODE 0x00000002
/* CSTYLED */
/**%
* safestore in NVRAM on a dual node system. all data is store remotely.
*/
#define SS_M_NV_DUALNODE_NOMIRROR 0x00000004
/* CSTYLED */
/**%
* safestore in NVRAM on a dual node system. data is mirrored on both nodes.
*/
#define SS_M_NV_DUALNODE_MIRROR 0x00000008
/* safestore data and metadata transport types */
/* CSTYLED */
/**%
* data is transferred using STE connection
*/
#define SS_T_STE 0x00010000
/* CSTYLED */
/**%
* data is transferred using RPC
*/
#define SS_T_RPC 0x00020000
/* CSTYLED */
/**%
* no transport -- (single node)
*/
#define SS_T_NONE 0x08000000
#define SS_MEDIA_MASK 0x0000ffff
#define SS_TRANSPORT_MASK 0xffff0000
#define _SD_NO_NET 0
#define _SD_NO_NETADDR 0
#define _SD_NO_HOST -1
#define _SD_NO_CD -1
/* config settings */
#define SS_UNCONFIGURED 0
#define SS_INITTED 1
#define SS_CONFIGURED 2
/* error return for safestore ops */
#define SS_ERR -1
#define SS_OK 0
#define SS_EOF 1
/* config flag */
#define SS_GENPATTERN 1
/*
* convenience macros. should they be implemented in ss_ctl()?
*/
/* is safestore on a single node? */
/* is safestore really safe or is it just RAM? */
/* is recovery needed with this safestore module? */
/* CSTYLED */
/**$
* configuration structure provided by safestore client
*
* @field ssc_configured set by safestore module to indicate config completed
* @field ssc_ss_psize safestore internal page size, set by ss module
* @field ssc_client_psize callers page size
* @field ssc_wsize cache size in bytes: amount of data that can be safestored
* @field ssc_maxfiles maximum number of volumes
* @field ssc_pattern initialization pattern if any
* @field ssc_flag use ssc_pattern if this is SS_GENPATTERN
*/
typedef struct ss_common_config_s {
int ssc_maxfiles; /* max files */
/* BEGIN CSTYLED */
/**$
* safestore operations structure
*
* @field ssop_name description of this module.
* @field ssop_type media type OR'd with transport type
* @field ssop_flags SS_RECOVERY_NEEDED
* @field ssop_configure configure the module
* @field ssop_deconfigure deconfigure the module
* @field ssop_getvdir get a volume directory stream according to type
* @field ssop_getvdirent get next entry in a volume directory stream
* @field ssop_getvol get the data for a volume
* @field ssop_setvol set the data for a volume
* @field ssop_getcdir get cache entry directory stream according to type
* @field ssop_getcdirent get next cache entry in stream
* @field ssop_allocresource allocate safestore resources from free list
* @field ssop_deallocresource deallocate, i.e. free, a safestore resource
* @field ssop_getresource get next resource in resource list
* @field ssop_getcentry get metadata for a cache entry
* @field ssop_setcentry set the metadata for a cache entry
* @field ssop_read_cblock read the actual data for a cache entry
* @field ssop_write_cblock write the data for a cache entry
* @field ssop_ctl module entry point for everything else, e.g. stats
*
* @see ss_vdirkey_t{}
* @see ss_voldata_t{}
* @see ss_cdirkey_t{}
* @see ss_resourcelist_t{}
* @see ss_resource_t{}
* @see ss_centry_info_t{}
*/
typedef struct safestore_ops_s {
char *ssop_name;
int (* ssop_deconfigure)(int);
int (* ssop_getvol)(ss_voldata_t *);
int (* ssop_setvol)(const ss_voldata_t *);
int (* ssop_allocresource)(int, int *, ss_resourcelist_t **);
void (* ssop_deallocresource)(ss_resource_t *);
int (* ssop_getcentry)(ss_centry_info_t *);
int (* ssop_setcentry)(const ss_centry_info_t *);
int (* ssop_read_cblock)(const ss_resource_t *, void *, int, int);
int (* ssop_write_cblock)(const ss_resource_t *,
const void *, int, int);
/* END CSTYLED */
/* ssop_flags */
/*
* no writes permitted when this bit is set in ssop flags field
* (single node nvram mostly)
*/
#define SS_RECOVERY_NEEDED 1
/* safestore operations */
/* BEGIN CSTYLED */
/**#
* SSOP_CONFIGURE() configure a safestore module
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param cfg a pointer to ss_common_config_t, initialized by caller
* @param kstatus unistat spcs_s_info_t
* @return SS_OK successful, errno otherwise
*
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_common_config_t{}
*/
/**#
* SSOP_DECONFIGURE deconfigure a safestore module
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param dirty integer flag, if set it signifies there is pinned data
* @return SS_OK success, SS_ERR otherwise
*
* @see safestore_ops_t{}
*/
/* volume directory functions */
/**#
* SSOP_GETVDIR get a volume directory stream according to type
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param key pointer to ss_vdirkey_t initialized by caller
* @param vdir pointer to ss_vdir_t owned by caller
* @return SS_OK success, SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see ss_vdirkey_t{}
* @see ss_vdir_t{}
*/
/**#
* SSOP_GETVDIRENT get next volume in a volume directory stream
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param vdir pointer to a properly initialized ss_vdir_t obtained
* from a successsful SSOP_GETVDIR() call
* @param voldata pointer to ss_voldata_t owned by caller, filled
* in with valid data on successful return
* @return SS_OK success
* SS_EOF if no more elements in stream,
* SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_vdir_t{}
* @see ss_voldata_t{}
* @see SSOP_GETVDIR()
*/
/* volume accessor functions */
/**#
* SSOP_GETVOL get the volume data for a particular volume
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param voldata pointer to ss_voldata_t owned by caller, field sv_vol
* must be initialized with a valid ss_vol_t, normally
* obtained from a successful SSOP_GETVDIRENT() call.
* the rest of the structure is filled with valid volume data
* on successful return
* @return SS_OK if data read successfully
* SS_ERR otherwise
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_voldata_t{}
* @see ss_vol_t{}
* @see SSOP_GETVDIRENT()
*/
/**#
* SSOP_SETVOL set the volume data for a particular volume
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param voldata pointer to ss_voldata_t owned by caller, field sv_vol
* must be initialized with a valid ss_vol_t, obtained from
* a successful SSOP_GETVDIRENT() call. the remaining
* fields of the structure are written to safestore
* @return SS_OK if data saved successfully
* SS_ERR otherwise
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_voldata_t{}
* @see ss_vol_t{}
* @see SSOP_GETVDIRENT()
*/
/* centry directory functions */
/**#
* SSOP_GETCDIR get a cache entry stream accroding to type
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param key pointer to a ss_cdirkey_t initialized by caller
* @param cdir pointer to ss_cdir_t owned by caller
* @return SS_OK success, SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_cdirkey_t{}
* @ see ss_cdir_t{}
*/
/**#
* SSOP_GETCDIRENT get next cache entry in a cache entry stream
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param cdir pointer to valid ss_cdirkey_t obtained from a
* successsful SSOP_GETCDIR call
* @param voldata pointer to ss_voldata_t owned by caller, filled
* in with valid data on successful return
* @return SS_OK success
* SS_EOF if no more elements in stream,
* SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_vdirkey_t{}
* @see ss_voldata_t{}
* @see SSOP_GETVDIR()
*/
/* cache entry alloc functions */
/**#
* SSOP_ALLOCRESOURCE allocate safestore resources from the free list
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param count number of resources, that is data blocks, needed
* @param stall integer pointer to stall count, no blocks available. used only
* when _sd_wblk_sync === 0
* @param reslist pointer to pointer to ss_resourcelist_t. points to valid
* resource list on successful return
* @return SS_OK success
* SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see ss_resourcelist_t{}
* @see SSOP_DEALLOCRESOURCE()
* @see SSOP_GETRESOURCE()
*/
/**#
* SSOP_DEALLOCRESOURCE deallocate, i.e. release, a single safestore resource
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param res pointer to ss_resource_t to be released
* @return void
*
* @see safestore_ops_t{}
* @see ss_resource_t{}
* @see SSOP_ALLOCRESOURCE()
* @see SSOP_GETRESOURCE()
*/
/**#
* SSOP_GETRESOURCE get the next safestore resource in a list
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param reslist pointer to pointer to ss_resourcelist_t obtained from
* a successful call to SSOP_ALLOCRESOURCE()
* @param res pointer to pointer to ss_resource_t. points to a valid
* on successful resource
* @return SS_OK success
* SS_EOF if no more resources in list
* SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see ss_resourcelist_t{}
* @see ss_resource_t{}
* @see SSOP_ALLOCRESOURCE()
* @see SSOP_DEALLOCRESOURCE()
*/
/* centry accessor functions */
/**#
* SSOP_GETCENTRY read cache entry metadata for a particular cache entry
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param centry_info pointer to ss_centry_info_t owned by caller.
* field sc_res must point to a valid ss_resource_t
* obtained from a successful call to SSOP_GETRESOURCE().
* the rest of the structure is filled with valid
* metadata on successful return
* @return SS_OK if data was read successfully
* SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_centry_info_t
* @see ss_resource_t{}
* @see SSOP_GETRESOURCE()
*/
/**#
* SSOP_SETCENTRY write cache entry metadata for a particular cache entry
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param centry_info pointer to ss_centry_info_t owned by caller.
* field sc_res must point to a valid ss_resource_t
* obtained from a successful call to SSOP_GETRESOURCE().
* the remaining fields of the structured are written
* to safestore.
* @return SS_OK if data was written successfully
* SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_centry_info_t{}
* @see ss_resource_t{}
* @see SSOP_GETRESOURCE()
*/
/**#
* SSOP_READ_CBLOCK read cache data for a particular cache entry
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param resource pointer to ss_resource_t obtained from a successful
* call to SSOP_GETRESOURCE().
* @param buf buffer to hold the data
* @param nbyte number of bytes to read
* @param srcoffset byte location from beginning of the cache block
* represented by resource to read the data from
*
* @return SS_OK if data was read successfully
* SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_resource_t{}
* @see SSOP_GETRESOURCE()
*/
/**#
* SSOP_WRITE_CBLOCK write cache data for a particular cache entry
* @param ssp a safestore_ops_t pointer obtained from sst_open()
* @param resource pointer to ss_resource_t obtained from a successful
* call to SSOP_GETRESOURCE().
* @param buf buffer to hold the data
* @param nbyte number of bytes to write
* @param destoffset byte location from beginning the cache block
* represented by resource to write the data to
*
* @return SS_OK if data was read successfully
* SS_ERR otherwise
*
* @see safestore_ops_t{}
* @see sst_open()
* @see ss_resource_t{}
* @see SSOP_GETRESOURCE()
*/
/**#
* SSOP_CTL perform a safestore control function
* @param cmd integer specifying the command to execute, e.g. SSIOC_STATS.
* some commands may be specific to a safestore module type
* @param arg a uintptr_t that has additional information that is
* needed by the safestore module to perform the command. it
* may be an int or a pionter to a module specifc structure.
* @return SS_OK success
* errno otherwise
*/
/* END CSTYLED */
/* general control definitions supported by safestore modules */
/* structure definitions */
typedef struct ssioc_stats_s {
int wq_inq; /* write queue count */
extern void sst_init();
extern void sst_register_mod(safestore_ops_t *);
extern void sst_unregister_mod(safestore_ops_t *);
extern int sst_close(safestore_ops_t *);
extern safestore_ops_t *sdbc_safestore;
extern int _sd_centry_shift;
#endif /* _KERNEL */
#ifdef __cplusplus
}
#endif
#endif /* _SD_SAFESTORE_H */