fs/ocfs2/stackglue.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * stackglue.h
0004  *
0005  * Glue to the underlying cluster stack.
0006  *
0007  * Copyright (C) 2007 Oracle.  All rights reserved.
0008  */
0009
0010
0011 #ifndef STACKGLUE_H
0012 #define STACKGLUE_H
0013
0014 #include <linux/types.h>
0015 #include <linux/list.h>
0016 #include <linux/dlmconstants.h>
0017
0018 #include "dlm/dlmapi.h"
0019 #include <linux/dlm.h>
0020
0021 /* Needed for plock-related prototypes */
0022 struct file;
0023 struct file_lock;
0024
0025 /*
0026  * dlmconstants.h does not have a LOCAL flag.  We hope to remove it
0027  * some day, but right now we need it.  Let's fake it.  This value is larger
0028  * than any flag in dlmconstants.h.
0029  */
0030 #define DLM_LKF_LOCAL       0x00100000
0031
0032 /*
0033  * This shadows DLM_LOCKSPACE_LEN in fs/dlm/dlm_internal.h.  That probably
0034  * wants to be in a public header.
0035  */
0036 #define GROUP_NAME_MAX      64
0037
0038 /* This shadows  OCFS2_CLUSTER_NAME_LEN */
0039 #define CLUSTER_NAME_MAX    16
0040
0041
0042 /*
0043  * ocfs2_protocol_version changes when ocfs2 does something different in
0044  * its inter-node behavior.  See dlmglue.c for more information.
0045  */
0046 struct ocfs2_protocol_version {
0047     u8 pv_major;
0048     u8 pv_minor;
0049 };
0050
0051 /*
0052  * The dlm_lockstatus struct includes lvb space, but the dlm_lksb struct only
0053  * has a pointer to separately allocated lvb space.  This struct exists only to
0054  * include in the lksb union to make space for a combined dlm_lksb and lvb.
0055  */
0056 struct fsdlm_lksb_plus_lvb {
0057     struct dlm_lksb lksb;
0058     char lvb[DLM_LVB_LEN];
0059 };
0060
0061 /*
0062  * A union of all lock status structures.  We define it here so that the
0063  * size of the union is known.  Lock status structures are embedded in
0064  * ocfs2 inodes.
0065  */
0066 struct ocfs2_cluster_connection;
0067 struct ocfs2_dlm_lksb {
0068      union {
0069          struct dlm_lockstatus lksb_o2dlm;
0070          struct dlm_lksb lksb_fsdlm;
0071          struct fsdlm_lksb_plus_lvb padding;
0072      };
0073      struct ocfs2_cluster_connection *lksb_conn;
0074 };
0075
0076 /*
0077  * The ocfs2_locking_protocol defines the handlers called on ocfs2's behalf.
0078  */
0079 struct ocfs2_locking_protocol {
0080     struct ocfs2_protocol_version lp_max_version;
0081     void (*lp_lock_ast)(struct ocfs2_dlm_lksb *lksb);
0082     void (*lp_blocking_ast)(struct ocfs2_dlm_lksb *lksb, int level);
0083     void (*lp_unlock_ast)(struct ocfs2_dlm_lksb *lksb, int error);
0084 };
0085
0086
0087 /*
0088  * A cluster connection.  Mostly opaque to ocfs2, the connection holds
0089  * state for the underlying stack.  ocfs2 does use cc_version to determine
0090  * locking compatibility.
0091  */
0092 struct ocfs2_cluster_connection {
0093     char cc_name[GROUP_NAME_MAX + 1];
0094     int cc_namelen;
0095     char cc_cluster_name[CLUSTER_NAME_MAX + 1];
0096     int cc_cluster_name_len;
0097     struct ocfs2_protocol_version cc_version;
0098     struct ocfs2_locking_protocol *cc_proto;
0099     void (*cc_recovery_handler)(int node_num, void *recovery_data);
0100     void *cc_recovery_data;
0101     void *cc_lockspace;
0102     void *cc_private;
0103 };
0104
0105 /*
0106  * Each cluster stack implements the stack operations structure.  Not used
0107  * in the ocfs2 code, the stackglue code translates generic cluster calls
0108  * into stack operations.
0109  */
0110 struct ocfs2_stack_operations {
0111     /*
0112      * The fs code calls ocfs2_cluster_connect() to attach a new
0113      * filesystem to the cluster stack.  The ->connect() op is passed
0114      * an ocfs2_cluster_connection with the name and recovery field
0115      * filled in.
0116      *
0117      * The stack must set up any notification mechanisms and create
0118      * the filesystem lockspace in the DLM.  The lockspace should be
0119      * stored on cc_lockspace.  Any other information can be stored on
0120      * cc_private.
0121      *
0122      * ->connect() must not return until it is guaranteed that
0123      *
0124      *  - Node down notifications for the filesystem will be received
0125      *    and passed to conn->cc_recovery_handler().
0126      *  - Locking requests for the filesystem will be processed.
0127      */
0128     int (*connect)(struct ocfs2_cluster_connection *conn);
0129
0130     /*
0131      * The fs code calls ocfs2_cluster_disconnect() when a filesystem
0132      * no longer needs cluster services.  All DLM locks have been
0133      * dropped, and recovery notification is being ignored by the
0134      * fs code.  The stack must disengage from the DLM and discontinue
0135      * recovery notification.
0136      *
0137      * Once ->disconnect() has returned, the connection structure will
0138      * be freed.  Thus, a stack must not return from ->disconnect()
0139      * until it will no longer reference the conn pointer.
0140      *
0141      * Once this call returns, the stack glue will be dropping this
0142      * connection's reference on the module.
0143      */
0144     int (*disconnect)(struct ocfs2_cluster_connection *conn);
0145
0146     /*
0147      * ->this_node() returns the cluster's unique identifier for the
0148      * local node.
0149      */
0150     int (*this_node)(struct ocfs2_cluster_connection *conn,
0151              unsigned int *node);
0152
0153     /*
0154      * Call the underlying dlm lock function.  The ->dlm_lock()
0155      * callback should convert the flags and mode as appropriate.
0156      *
0157      * ast and bast functions are not part of the call because the
0158      * stack will likely want to wrap ast and bast calls before passing
0159      * them to stack->sp_proto.  There is no astarg.  The lksb will
0160      * be passed back to the ast and bast functions.  The caller can
0161      * use this to find their object.
0162      */
0163     int (*dlm_lock)(struct ocfs2_cluster_connection *conn,
0164             int mode,
0165             struct ocfs2_dlm_lksb *lksb,
0166             u32 flags,
0167             void *name,
0168             unsigned int namelen);
0169
0170     /*
0171      * Call the underlying dlm unlock function.  The ->dlm_unlock()
0172      * function should convert the flags as appropriate.
0173      *
0174      * The unlock ast is not passed, as the stack will want to wrap
0175      * it before calling stack->sp_proto->lp_unlock_ast().  There is
0176      * no astarg.  The lksb will be passed back to the unlock ast
0177      * function.  The caller can use this to find their object.
0178      */
0179     int (*dlm_unlock)(struct ocfs2_cluster_connection *conn,
0180               struct ocfs2_dlm_lksb *lksb,
0181               u32 flags);
0182
0183     /*
0184      * Return the status of the current lock status block.  The fs
0185      * code should never dereference the union.  The ->lock_status()
0186      * callback pulls out the stack-specific lksb, converts the status
0187      * to a proper errno, and returns it.
0188      */
0189     int (*lock_status)(struct ocfs2_dlm_lksb *lksb);
0190
0191     /*
0192      * Return non-zero if the LVB is valid.
0193      */
0194     int (*lvb_valid)(struct ocfs2_dlm_lksb *lksb);
0195
0196     /*
0197      * Pull the lvb pointer off of the stack-specific lksb.
0198      */
0199     void *(*lock_lvb)(struct ocfs2_dlm_lksb *lksb);
0200
0201     /*
0202      * Cluster-aware posix locks
0203      *
0204      * This is NULL for stacks which do not support posix locks.
0205      */
0206     int (*plock)(struct ocfs2_cluster_connection *conn,
0207              u64 ino,
0208              struct file *file,
0209              int cmd,
0210              struct file_lock *fl);
0211
0212     /*
0213      * This is an optoinal debugging hook.  If provided, the
0214      * stack can dump debugging information about this lock.
0215      */
0216     void (*dump_lksb)(struct ocfs2_dlm_lksb *lksb);
0217 };
0218
0219 /*
0220  * Each stack plugin must describe itself by registering a
0221  * ocfs2_stack_plugin structure.  This is only seen by stackglue and the
0222  * stack driver.
0223  */
0224 struct ocfs2_stack_plugin {
0225     char *sp_name;
0226     struct ocfs2_stack_operations *sp_ops;
0227     struct module *sp_owner;
0228
0229     /* These are managed by the stackglue code. */
0230     struct list_head sp_list;
0231     unsigned int sp_count;
0232     struct ocfs2_protocol_version sp_max_proto;
0233 };
0234
0235
0236 /* Used by the filesystem */
0237 int ocfs2_cluster_connect(const char *stack_name,
0238               const char *cluster_name,
0239               int cluster_name_len,
0240               const char *group,
0241               int grouplen,
0242               struct ocfs2_locking_protocol *lproto,
0243               void (*recovery_handler)(int node_num,
0244                            void *recovery_data),
0245               void *recovery_data,
0246               struct ocfs2_cluster_connection **conn);
0247 /*
0248  * Used by callers that don't store their stack name.  They must ensure
0249  * all nodes have the same stack.
0250  */
0251 int ocfs2_cluster_connect_agnostic(const char *group,
0252                    int grouplen,
0253                    struct ocfs2_locking_protocol *lproto,
0254                    void (*recovery_handler)(int node_num,
0255                                 void *recovery_data),
0256                    void *recovery_data,
0257                    struct ocfs2_cluster_connection **conn);
0258 int ocfs2_cluster_disconnect(struct ocfs2_cluster_connection *conn,
0259                  int hangup_pending);
0260 void ocfs2_cluster_hangup(const char *group, int grouplen);
0261 int ocfs2_cluster_this_node(struct ocfs2_cluster_connection *conn,
0262                 unsigned int *node);
0263
0264 struct ocfs2_lock_res;
0265 int ocfs2_dlm_lock(struct ocfs2_cluster_connection *conn,
0266            int mode,
0267            struct ocfs2_dlm_lksb *lksb,
0268            u32 flags,
0269            void *name,
0270            unsigned int namelen);
0271 int ocfs2_dlm_unlock(struct ocfs2_cluster_connection *conn,
0272              struct ocfs2_dlm_lksb *lksb,
0273              u32 flags);
0274
0275 int ocfs2_dlm_lock_status(struct ocfs2_dlm_lksb *lksb);
0276 int ocfs2_dlm_lvb_valid(struct ocfs2_dlm_lksb *lksb);
0277 void *ocfs2_dlm_lvb(struct ocfs2_dlm_lksb *lksb);
0278 void ocfs2_dlm_dump_lksb(struct ocfs2_dlm_lksb *lksb);
0279
0280 int ocfs2_stack_supports_plocks(void);
0281 int ocfs2_plock(struct ocfs2_cluster_connection *conn, u64 ino,
0282         struct file *file, int cmd, struct file_lock *fl);
0283
0284 void ocfs2_stack_glue_set_max_proto_version(struct ocfs2_protocol_version *max_proto);
0285
0286
0287 /* Used by stack plugins */
0288 int ocfs2_stack_glue_register(struct ocfs2_stack_plugin *plugin);
0289 void ocfs2_stack_glue_unregister(struct ocfs2_stack_plugin *plugin);
0290
0291 extern struct kset *ocfs2_kset;
0292
0293 #endif  /* STACKGLUE_H */