libmultipath/checkers.h

   1 #ifndef _CHECKERS_H
   2 #define _CHECKERS_H
   3
   4 #include "list.h"
   5 #include "memory.h"
   6 #include "defaults.h"
   7
   8 /*
   9  *
  10  * Userspace (multipath/multipathd) path states
  11  *
  12  * PATH_WILD:
  13  * - Use: None of the checkers (returned if we don't have an fd)
  14  * - Description: Corner case where "fd < 0" for path fd (see checker_check())
  15  *
  16  * PATH_UNCHECKED:
  17  * - Use: Only in directio checker
  18  * - Description: set when fcntl(F_GETFL) fails to return flags or O_DIRECT
  19  *   not include in flags, or O_DIRECT read fails
  20  * - Notes:
  21  *   - multipathd: uses it to skip over paths in sync_map_state()
  22  *   - multipath: used in update_paths(); if state==PATH_UNCHECKED, call
  23  *     pathinfo()
  24  *
  25  * PATH_DOWN:
  26  * - Use: All checkers (directio, emc_clariion, hp_sw, readsector0, tur)
  27  * - Description: Either a) SG_IO ioctl failed, or b) check condition on some
  28  *   SG_IO ioctls that succeed (tur, readsector0 checkers); path is down and
  29  *   you shouldn't try to send commands to it
  30  *
  31  * PATH_UP:
  32  * - Use: All checkers (directio, emc_clariion, hp_sw, readsector0, tur)
  33  * - Description: Path is up and I/O can be sent to it
  34  *
  35  * PATH_SHAKY:
  36  * - Use: Only emc_clariion
  37  * - Description: Indicates path not available for "normal" operations
  38  *
  39  * PATH_GHOST:
  40  * - Use: Only hp_sw and rdac
  41  * - Description: Indicates a "passive/standby" path on active/passive HP
  42  *   arrays.  These paths will return valid answers to certain SCSI commands
  43  *   (tur, read_capacity, inquiry, start_stop), but will fail I/O commands.
  44  *   The path needs an initialization command to be sent to it in order for
  45  *   I/Os to succeed.
  46  *
  47  * PATH_PENDING:
  48  * - Use: All async checkers
  49  * - Description: Indicates a check IO is in flight.
  50  *
  51  * PATH_TIMEOUT:
  52  * - Use: Only tur checker
  53  * - Description: Command timed out
  54  *
  55  * PATH REMOVED:
  56  * - Use: All checkers
  57  * - Description: Device has been removed from the system
  58  *
  59  * PATH_DELAYED:
  60  * - Use: None of the checkers (returned if the path is being delayed before
  61  *   reintegration.
  62  * - Description: If a path fails after being up for less than
  63  *   delay_watch_checks checks, when it comes back up again, it will not
  64  *   be marked as up until it has been up for delay_wait_checks checks.
  65  *   During this time, it is marked as "delayed"
  66  */
  67 enum path_check_state {
  68         PATH_WILD,
  69         PATH_UNCHECKED,
  70         PATH_DOWN,
  71         PATH_UP,
  72         PATH_SHAKY,
  73         PATH_GHOST,
  74         PATH_PENDING,
  75         PATH_TIMEOUT,
  76         PATH_REMOVED,
  77         PATH_DELAYED,
  78         PATH_MAX_STATE
  79 };
  80
  81 #define DIRECTIO     "directio"
  82 #define TUR          "tur"
  83 #define HP_SW        "hp_sw"
  84 #define RDAC         "rdac"
  85 #define EMC_CLARIION "emc_clariion"
  86 #define READSECTOR0  "readsector0"
  87 #define CCISS_TUR    "cciss_tur"
  88 #define NONE         "none"
  89
  90 #define ASYNC_TIMEOUT_SEC       30
  91
  92 /*
  93  * strings lengths
  94  */
  95 #define CHECKER_NAME_LEN 16
  96 #define CHECKER_MSG_LEN 256
  97 #define CHECKER_DEV_LEN 256
  98 #define LIB_CHECKER_NAMELEN 256
  99
 100 /*
 101  * Generic message IDs for use in checkers.
 102  */
 103 enum {
 104         CHECKER_MSGID_NONE = 0,
 105         CHECKER_MSGID_DISABLED,
 106         CHECKER_MSGID_NO_FD,
 107         CHECKER_MSGID_INVALID,
 108         CHECKER_MSGID_UP,
 109         CHECKER_MSGID_DOWN,
 110         CHECKER_MSGID_GHOST,
 111         CHECKER_GENERIC_MSGTABLE_SIZE,
 112         CHECKER_FIRST_MSGID = 100,      /* lowest msgid for checkers */
 113         CHECKER_MSGTABLE_SIZE = 100,    /* max msg table size for checkers */
 114 };
 115
 116 struct checker {
 117         struct list_head node;
 118         void *handle;
 119         int refcount;
 120         int fd;
 121         int sync;
 122         unsigned int timeout;
 123         int disable;
 124         char name[CHECKER_NAME_LEN];
 125         short msgid;                         /* checker-internal extra status */
 126         void * context;                      /* store for persistent data */
 127         void ** mpcontext;                   /* store for persistent data shared
 128                                                 multipath-wide. Use MALLOC if
 129                                                 you want to stuff data in. */
 130         int (*check)(struct checker *);
 131         int (*init)(struct checker *);       /* to allocate the context */
 132         void (*free)(struct checker *);      /* to free the context */
 133         const char**msgtable;
 134         short msgtable_size;
 135 };
 136
 137 char * checker_state_name (int);
 138 int init_checkers (char *);
 139 void cleanup_checkers (void);
 140 struct checker * add_checker (char *, char *);
 141 struct checker * checker_lookup (char *);
 142 int checker_init (struct checker *, void **);
 143 void checker_clear (struct checker *);
 144 void checker_put (struct checker *);
 145 void checker_reset (struct checker *);
 146 void checker_set_sync (struct checker *);
 147 void checker_set_async (struct checker *);
 148 void checker_set_fd (struct checker *, int);
 149 void checker_enable (struct checker *);
 150 void checker_disable (struct checker *);
 151 int checker_check (struct checker *, int);
 152 int checker_selected (struct checker *);
 153 const char *checker_name (const struct checker *);
 154 /*
 155  * This returns a string that's best prepended with "$NAME checker",
 156  * where $NAME is the return value of checker_name().
 157  */
 158 const char *checker_message(const struct checker *);
 159 void checker_clear_message (struct checker *c);
 160 void checker_get (char *, struct checker *, char *);
 161
 162 /* Prototypes for symbols exported by path checker dynamic libraries (.so) */
 163 int libcheck_check(struct checker *);
 164 int libcheck_init(struct checker *);
 165 void libcheck_free(struct checker *);
 166 /*
 167  * msgid => message map.
 168  *
 169  * It only needs to be provided if the checker defines specific
 170  * message IDs.
 171  * Message IDs available to checkers start at CHECKER_FIRST_MSG.
 172  * The msgtable array is 0-based, i.e. msgtable[0] is the message
 173  * for msgid == __CHECKER_FIRST_MSG.
 174  * The table ends with a NULL element.
 175  */
 176 extern const char *libcheck_msgtable[];
 177
 178 #endif /* _CHECKERS_H */