libmultipath/checkers: replace message by msgid
[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: 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 */