fs/ocfs2/stackglue.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * stackglue.h
   4  *
   5  * Glue to the underlying cluster stack.
   6  *
   7  * Copyright (C) 2007 Oracle.  All rights reserved.
   8  */
   9
  10
  11 #ifndef STACKGLUE_H
  12 #define STACKGLUE_H
  13
  14 #include <linux/types.h>
  15 #include <linux/list.h>
  16 #include <linux/dlmconstants.h>
  17
  18 #include "dlm/dlmapi.h"
  19 #include <linux/dlm.h>
  20
  21 /* Needed for plock-related prototypes */
  22 struct file;
  23 struct file_lock;
  24
  25 /*
  26  * dlmconstants.h does not have a LOCAL flag.  We hope to remove it
  27  * some day, but right now we need it.  Let's fake it.  This value is larger
  28  * than any flag in dlmconstants.h.
  29  */
  30 #define DLM_LKF_LOCAL           0x00100000
  31
  32 /*
  33  * This shadows DLM_LOCKSPACE_LEN in fs/dlm/dlm_internal.h.  That probably
  34  * wants to be in a public header.
  35  */
  36 #define GROUP_NAME_MAX          64
  37
  38 /* This shadows  OCFS2_CLUSTER_NAME_LEN */
  39 #define CLUSTER_NAME_MAX        16
  40
  41
  42 /*
  43  * ocfs2_protocol_version changes when ocfs2 does something different in
  44  * its inter-node behavior.  See dlmglue.c for more information.
  45  */
  46 struct ocfs2_protocol_version {
  47         u8 pv_major;
  48         u8 pv_minor;
  49 };
  50
  51 /*
  52  * The dlm_lockstatus struct includes lvb space, but the dlm_lksb struct only
  53  * has a pointer to separately allocated lvb space.  This struct exists only to
  54  * include in the lksb union to make space for a combined dlm_lksb and lvb.
  55  */
  56 struct fsdlm_lksb_plus_lvb {
  57         struct dlm_lksb lksb;
  58         char lvb[DLM_LVB_LEN];
  59 };
  60
  61 /*
  62  * A union of all lock status structures.  We define it here so that the
  63  * size of the union is known.  Lock status structures are embedded in
  64  * ocfs2 inodes.
  65  */
  66 struct ocfs2_cluster_connection;
  67 struct ocfs2_dlm_lksb {
  68          union {
  69                  struct dlm_lockstatus lksb_o2dlm;
  70                  struct dlm_lksb lksb_fsdlm;
  71                  struct fsdlm_lksb_plus_lvb padding;
  72          };
  73          struct ocfs2_cluster_connection *lksb_conn;
  74 };
  75
  76 /*
  77  * The ocfs2_locking_protocol defines the handlers called on ocfs2's behalf.
  78  */
  79 struct ocfs2_locking_protocol {
  80         struct ocfs2_protocol_version lp_max_version;
  81         void (*lp_lock_ast)(struct ocfs2_dlm_lksb *lksb);
  82         void (*lp_blocking_ast)(struct ocfs2_dlm_lksb *lksb, int level);
  83         void (*lp_unlock_ast)(struct ocfs2_dlm_lksb *lksb, int error);
  84 };
  85
  86
  87 /*
  88  * A cluster connection.  Mostly opaque to ocfs2, the connection holds
  89  * state for the underlying stack.  ocfs2 does use cc_version to determine
  90  * locking compatibility.
  91  */
  92 struct ocfs2_cluster_connection {
  93         char cc_name[GROUP_NAME_MAX + 1];
  94         int cc_namelen;
  95         char cc_cluster_name[CLUSTER_NAME_MAX + 1];
  96         int cc_cluster_name_len;
  97         struct ocfs2_protocol_version cc_version;
  98         struct ocfs2_locking_protocol *cc_proto;
  99         void (*cc_recovery_handler)(int node_num, void *recovery_data);
 100         void *cc_recovery_data;
 101         void *cc_lockspace;
 102         void *cc_private;
 103 };
 104
 105 /*
 106  * Each cluster stack implements the stack operations structure.  Not used
 107  * in the ocfs2 code, the stackglue code translates generic cluster calls
 108  * into stack operations.
 109  */
 110 struct ocfs2_stack_operations {
 111         /*
 112          * The fs code calls ocfs2_cluster_connect() to attach a new
 113          * filesystem to the cluster stack.  The ->connect() op is passed
 114          * an ocfs2_cluster_connection with the name and recovery field
 115          * filled in.
 116          *
 117          * The stack must set up any notification mechanisms and create
 118          * the filesystem lockspace in the DLM.  The lockspace should be
 119          * stored on cc_lockspace.  Any other information can be stored on
 120          * cc_private.
 121          *
 122          * ->connect() must not return until it is guaranteed that
 123          *
 124          *  - Node down notifications for the filesystem will be received
 125          *    and passed to conn->cc_recovery_handler().
 126          *  - Locking requests for the filesystem will be processed.
 127          */
 128         int (*connect)(struct ocfs2_cluster_connection *conn);
 129
 130         /*
 131          * The fs code calls ocfs2_cluster_disconnect() when a filesystem
 132          * no longer needs cluster services.  All DLM locks have been
 133          * dropped, and recovery notification is being ignored by the
 134          * fs code.  The stack must disengage from the DLM and discontinue
 135          * recovery notification.
 136          *
 137          * Once ->disconnect() has returned, the connection structure will
 138          * be freed.  Thus, a stack must not return from ->disconnect()
 139          * until it will no longer reference the conn pointer.
 140          *
 141          * Once this call returns, the stack glue will be dropping this
 142          * connection's reference on the module.
 143          */
 144         int (*disconnect)(struct ocfs2_cluster_connection *conn);
 145
 146         /*
 147          * ->this_node() returns the cluster's unique identifier for the
 148          * local node.
 149          */
 150         int (*this_node)(struct ocfs2_cluster_connection *conn,
 151                          unsigned int *node);
 152
 153         /*
 154          * Call the underlying dlm lock function.  The ->dlm_lock()
 155          * callback should convert the flags and mode as appropriate.
 156          *
 157          * ast and bast functions are not part of the call because the
 158          * stack will likely want to wrap ast and bast calls before passing
 159          * them to stack->sp_proto.  There is no astarg.  The lksb will
 160          * be passed back to the ast and bast functions.  The caller can
 161          * use this to find their object.
 162          */
 163         int (*dlm_lock)(struct ocfs2_cluster_connection *conn,
 164                         int mode,
 165                         struct ocfs2_dlm_lksb *lksb,
 166                         u32 flags,
 167                         void *name,
 168                         unsigned int namelen);
 169
 170         /*
 171          * Call the underlying dlm unlock function.  The ->dlm_unlock()
 172          * function should convert the flags as appropriate.
 173          *
 174          * The unlock ast is not passed, as the stack will want to wrap
 175          * it before calling stack->sp_proto->lp_unlock_ast().  There is
 176          * no astarg.  The lksb will be passed back to the unlock ast
 177          * function.  The caller can use this to find their object.
 178          */
 179         int (*dlm_unlock)(struct ocfs2_cluster_connection *conn,
 180                           struct ocfs2_dlm_lksb *lksb,
 181                           u32 flags);
 182
 183         /*
 184          * Return the status of the current lock status block.  The fs
 185          * code should never dereference the union.  The ->lock_status()
 186          * callback pulls out the stack-specific lksb, converts the status
 187          * to a proper errno, and returns it.
 188          */
 189         int (*lock_status)(struct ocfs2_dlm_lksb *lksb);
 190
 191         /*
 192          * Return non-zero if the LVB is valid.
 193          */
 194         int (*lvb_valid)(struct ocfs2_dlm_lksb *lksb);
 195
 196         /*
 197          * Pull the lvb pointer off of the stack-specific lksb.
 198          */
 199         void *(*lock_lvb)(struct ocfs2_dlm_lksb *lksb);
 200
 201         /*
 202          * Cluster-aware posix locks
 203          *
 204          * This is NULL for stacks which do not support posix locks.
 205          */
 206         int (*plock)(struct ocfs2_cluster_connection *conn,
 207                      u64 ino,
 208                      struct file *file,
 209                      int cmd,
 210                      struct file_lock *fl);
 211
 212         /*
 213          * This is an optoinal debugging hook.  If provided, the
 214          * stack can dump debugging information about this lock.
 215          */
 216         void (*dump_lksb)(struct ocfs2_dlm_lksb *lksb);
 217 };
 218
 219 /*
 220  * Each stack plugin must describe itself by registering a
 221  * ocfs2_stack_plugin structure.  This is only seen by stackglue and the
 222  * stack driver.
 223  */
 224 struct ocfs2_stack_plugin {
 225         char *sp_name;
 226         const struct ocfs2_stack_operations *sp_ops;
 227         struct module *sp_owner;
 228
 229         /* These are managed by the stackglue code. */
 230         struct list_head sp_list;
 231         unsigned int sp_count;
 232         struct ocfs2_protocol_version sp_max_proto;
 233 };
 234
 235
 236 /* Used by the filesystem */
 237 int ocfs2_cluster_connect(const char *stack_name,
 238                           const char *cluster_name,
 239                           int cluster_name_len,
 240                           const char *group,
 241                           int grouplen,
 242                           struct ocfs2_locking_protocol *lproto,
 243                           void (*recovery_handler)(int node_num,
 244                                                    void *recovery_data),
 245                           void *recovery_data,
 246                           struct ocfs2_cluster_connection **conn);
 247 /*
 248  * Used by callers that don't store their stack name.  They must ensure
 249  * all nodes have the same stack.
 250  */
 251 int ocfs2_cluster_connect_agnostic(const char *group,
 252                                    int grouplen,
 253                                    struct ocfs2_locking_protocol *lproto,
 254                                    void (*recovery_handler)(int node_num,
 255                                                             void *recovery_data),
 256                                    void *recovery_data,
 257                                    struct ocfs2_cluster_connection **conn);
 258 int ocfs2_cluster_disconnect(struct ocfs2_cluster_connection *conn,
 259                              int hangup_pending);
 260 void ocfs2_cluster_hangup(const char *group, int grouplen);
 261 int ocfs2_cluster_this_node(struct ocfs2_cluster_connection *conn,
 262                             unsigned int *node);
 263
 264 struct ocfs2_lock_res;
 265 int ocfs2_dlm_lock(struct ocfs2_cluster_connection *conn,
 266                    int mode,
 267                    struct ocfs2_dlm_lksb *lksb,
 268                    u32 flags,
 269                    void *name,
 270                    unsigned int namelen);
 271 int ocfs2_dlm_unlock(struct ocfs2_cluster_connection *conn,
 272                      struct ocfs2_dlm_lksb *lksb,
 273                      u32 flags);
 274
 275 int ocfs2_dlm_lock_status(struct ocfs2_dlm_lksb *lksb);
 276 int ocfs2_dlm_lvb_valid(struct ocfs2_dlm_lksb *lksb);
 277 void *ocfs2_dlm_lvb(struct ocfs2_dlm_lksb *lksb);
 278 void ocfs2_dlm_dump_lksb(struct ocfs2_dlm_lksb *lksb);
 279
 280 int ocfs2_stack_supports_plocks(void);
 281 int ocfs2_plock(struct ocfs2_cluster_connection *conn, u64 ino,
 282                 struct file *file, int cmd, struct file_lock *fl);
 283
 284 void ocfs2_stack_glue_set_max_proto_version(struct ocfs2_protocol_version *max_proto);
 285
 286
 287 /* Used by stack plugins */
 288 int ocfs2_stack_glue_register(struct ocfs2_stack_plugin *plugin);
 289 void ocfs2_stack_glue_unregister(struct ocfs2_stack_plugin *plugin);
 290
 291 extern struct kset *ocfs2_kset;
 292
 293 #endif  /* STACKGLUE_H */