dab197f9c53440184b0ab78bc6f7273911ab0702
[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_class;
120 struct checker {
121         struct checker_class *cls;
122         int fd;
123         unsigned int timeout;
124         int disable;
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 };
131
132 static inline int checker_selected(const struct checker *c)
133 {
134         return c != NULL && c->cls != NULL;
135 }
136
137 const char *checker_state_name(int);
138 int init_checkers(const char *);
139 void cleanup_checkers (void);
140 int checker_init (struct checker *, void **);
141 void checker_clear (struct checker *);
142 void checker_put (struct checker *);
143 void checker_reset (struct checker *);
144 void checker_set_sync (struct checker *);
145 void checker_set_async (struct checker *);
146 void checker_set_fd (struct checker *, int);
147 void checker_enable (struct checker *);
148 void checker_disable (struct checker *);
149 int checker_check (struct checker *, int);
150 int checker_is_sync(const struct checker *);
151 const char *checker_name (const struct checker *);
152 /*
153  * This returns a string that's best prepended with "$NAME checker",
154  * where $NAME is the return value of checker_name().
155  */
156 const char *checker_message(const struct checker *);
157 void checker_clear_message (struct checker *c);
158 void checker_get(const char *, struct checker *, const char *);
159
160 /* Prototypes for symbols exported by path checker dynamic libraries (.so) */
161 int libcheck_check(struct checker *);
162 int libcheck_init(struct checker *);
163 void libcheck_free(struct checker *);
164 /*
165  * msgid => message map.
166  *
167  * It only needs to be provided if the checker defines specific
168  * message IDs.
169  * Message IDs available to checkers start at CHECKER_FIRST_MSG.
170  * The msgtable array is 0-based, i.e. msgtable[0] is the message
171  * for msgid == __CHECKER_FIRST_MSG.
172  * The table ends with a NULL element.
173  */
174 extern const char *libcheck_msgtable[];
175
176 #endif /* _CHECKERS_H */