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