multipathd: fix reservation_key check
[multipath-tools/.git] / libmultipath / foreign.h
1 /*
2   Copyright (c) 2018 Martin Wilck, SUSE Linux GmbH
3
4   This program is free software; you can redistribute it and/or
5   modify it under the terms of the GNU General Public License
6   as published by the Free Software Foundation; either version 2
7   of the License, or (at your option) any later version.
8
9   This program is distributed in the hope that it will be useful,
10   but WITHOUT ANY WARRANTY; without even the implied warranty of
11   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12   GNU General Public License for more details.
13
14   You should have received a copy of the GNU General Public License
15   along with this program; if not, write to the Free Software
16   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
17   USA.
18 */
19 #ifndef _FOREIGN_H
20 #define _FOREIGN_H
21 #include <stdbool.h>
22 #include <libudev.h>
23
24 #define LIBMP_FOREIGN_API ((1 << 8) | 0)
25
26 struct context;
27
28 /* return codes of functions below returning "int" */
29 enum foreign_retcode {
30         FOREIGN_OK,
31         FOREIGN_CLAIMED,
32         FOREIGN_IGNORED,
33         FOREIGN_UNCLAIMED,
34         FOREIGN_NODEV,
35         FOREIGN_ERR,
36         __LAST_FOREIGN_RETCODE,
37 };
38
39 /**
40  * Foreign multipath library API
41  * Foreign libraries must implement the following methods.
42  */
43 struct foreign {
44         /**
45          * method: init(api, name)
46          * Initialize foreign library, and check API compatibility
47          * return pointer to opaque internal data strucure if successful,
48          * NULL otherwise.
49          *
50          * @param[in] api: API version
51          * @param[in] name: name to use for references to self in log messages,
52          *     doesn't need to be strdup'd
53          * @returns context pointer to use in future method calls.
54          */
55         struct context* (*init)(unsigned int api, const char *name);
56
57         /**
58          * method: cleanup(context)
59          * Free data structures used by foreign library, including
60          * context itself.
61          *
62          * @param[in] context foreign library context. This shouldn't be
63          * referenced any more after calling cleanup().
64          */
65         void (*cleanup)(struct context *);
66
67         /**
68          * method: add(context, udev)
69          * This is called during path detection, and for udev ADD events.
70          *
71          * @param[in] context foreign library context
72          * @param[in] udev udev device to add
73          * @returns status code
74          * @retval FOREIGN_CLAIMED: device newly claimed
75          * @retval FOREIGN_OK: device already registered, no action taken
76          * @retval FOREIGN_IGNORED: device is ignored, no action taken
77          * @retval FOREIGN_ERR: an error occurred (e.g. out-of-memory)
78          */
79         int (*add)(struct context *, struct udev_device *);
80
81         /**
82          * method: change
83          * This is called on udev CHANGE events.
84          *
85          * @param[in] context foreign library context
86          * @param[in] udev udev device that has generated the event
87          * @returns status code
88          * @retval FOREIGN_OK: event processed
89          * @retval FOREIGN_IGNORED: the device is ignored
90          * @retval FOREIGN_ERR: an error occurred (e.g. out-of-memory)
91          *
92          * Note: theoretically it can happen that the status of a foreign device
93          * (claimed vs. not claimed) changes in a change event.
94          * Supporting this correctly would require big efforts. For now, we
95          * don't support it. "multipathd reconfigure" starts foreign device
96          * detection from scratch and should be able to handle this situation.
97          */
98         int (*change)(struct context *, struct udev_device *);
99
100         /**
101          * method: delete
102          * This is called on udev DELETE events.
103          *
104          * @param[in] context foreign library context
105          * @param[in] udev udev device that has generated the event and
106          *      should be deleted
107          * @returns status code
108          * @retval FOREIGN_OK: processed correctly (device deleted)
109          * @retval FOREIGN_IGNORED: device wasn't registered internally
110          * @retval FOREIGN_ERR: error occurred.
111          */
112         int (*delete)(struct context *, struct udev_device *);
113
114         /**
115          * method: delete_all
116          * This is called if multipathd reconfigures itself.
117          * Deletes all registered devices (maps and paths)
118          *
119          * @param[in] context foreign library context
120          * @returns status code
121          * @retval FOREIGN_OK: processed correctly
122          * @retval FOREIGN_IGNORED: nothing to delete
123          * @retval FOREIGN_ERR: error occurred
124          */
125         int (*delete_all)(struct context*);
126
127         /**
128          * method: check
129          * This is called from multipathd's checker loop.
130          *
131          * Check status of managed devices, update internal status, and print
132          * log messages if appropriate.
133          * @param[in] context foreign library context
134          */
135         void (*check)(struct context *);
136
137         /**
138          * lock internal data structures.
139          * @param[in] ctx: foreign context
140          */
141         void (*lock)(struct context *ctx);
142
143         /**
144          * unlock internal data structures.
145          * @param[in] ctx: foreign context (void* in order to use the function
146          *      as argument to pthread_cleanup_push())
147          */
148         void (*unlock)(void *ctx);
149
150         /**
151          * method: get_multipaths(context)
152          * Returned vector must be freed by calling release_multipaths().
153          * Lock must be held until release_multipaths() is called.
154          *
155          * @param[in] context foreign library context
156          * @returns a vector of "struct gen_multipath*" with the map devices
157          * belonging to this library (see generic.h).
158          */
159         const struct _vector* (*get_multipaths)(const struct context *);
160
161         /**
162          * method: release_multipaths(context, mpvec)
163          * release data structures obtained with get_multipaths (if any)
164          *
165          * @param[in] ctx the foreign context
166          * @param[in] mpvec the vector allocated with get_multipaths()
167          */
168         void (*release_multipaths)(const struct context *ctx,
169                                    const struct _vector* mpvec);
170
171         /**
172          * method: get_paths
173          * Returned vector must be freed by calling release_paths().
174          * Lock must be held until release_paths() is called.
175          *
176          * @param[in] context foreign library context
177          * @returns a vector of "struct gen_path*" with the path devices
178          * belonging to this library (see generic.h)
179          */
180         const struct _vector* (*get_paths)(const struct context *);
181
182         /**
183          * release data structures obtained with get_multipaths (if any)
184          *
185          * @param[in] ctx the foreign context
186          * @param[in] ppvec the vector allocated with get_paths()
187          */
188         void (*release_paths)(const struct context *ctx,
189                               const struct _vector* ppvec);
190
191         void *handle;
192         struct context *context;
193         const char name[0];
194 };
195
196 /**
197  * init_foreign(dir)
198  * load and initialize foreign multipath libraries in dir (libforeign-*.so).
199  * @param dir: directory to search
200  * @returns: 0 on success, negative value on failure.
201  */
202 int init_foreign(const char *multipath_dir);
203
204 /**
205  * cleanup_foreign(dir)
206  * cleanup and free all data structures owned by foreign libraries
207  */
208 void cleanup_foreign(void);
209
210 /**
211  * add_foreign(udev)
212  * check if a device belongs to any foreign library.
213  * calls add() for all known foreign libs, in the order registered,
214  * until the first one returns FOREIGN_CLAIMED or FOREIGN_OK.
215  * @param udev: udev device to check
216  * @returns: status code
217  * @retval FOREIGN_CLAIMED: newly claimed by a foreign lib
218  * @retval FOREIGN_OK: already claimed by a foreign lib
219  * @retval FOREIGN_IGNORED: ignored by all foreign libs
220  * @retval FOREIGN_ERR: an error occurred
221  */
222 int add_foreign(struct udev_device *);
223
224 /**
225  * change_foreign(udev)
226  * Notify foreign libraries of an udev CHANGE event
227  * @param udev: udev device to check
228  * @returns: status code (see change() method above).
229  */
230 int change_foreign(struct udev_device *);
231
232 /**
233  * delete_foreign(udev)
234  * @param udev: udev device being removed
235  * @returns: status code (see remove() above)
236  */
237 int delete_foreign(struct udev_device *);
238
239 /**
240  * delete_all_foreign()
241  * call delete_all() for all foreign libraries
242  * @returns: status code (see delete_all() above)
243  */
244 int delete_all_foreign(void);
245
246 /**
247  * check_foreign()
248  * call check() (see above) for all foreign libraries
249  */
250 void check_foreign(void);
251
252 /**
253  * foreign_path_layout()
254  * call this before printing paths, after get_path_layout(), to determine
255  * output field width.
256  */
257 void foreign_path_layout(void);
258
259 /**
260  * foreign_multipath_layout()
261  * call this before printing maps, after get_multipath_layout(), to determine
262  * output field width.
263  */
264 void foreign_multipath_layout(void);
265
266 /**
267  * snprint_foreign_topology(buf, len, verbosity);
268  * prints topology information from foreign libraries into buffer,
269  * '\0' - terminated.
270  * @param buf: output buffer
271  * @param len: size of output buffer
272  * @param verbosity: verbosity level
273  * @returns: number of printed characters excluding trailing '\0'.
274  */
275 int snprint_foreign_topology(char *buf, int len, int verbosity);
276
277 /**
278  * snprint_foreign_paths(buf, len, style, pad);
279  * prints formatted path information from foreign libraries into buffer,
280  * '\0' - terminated.
281  * @param buf: output buffer
282  * @param len: size of output buffer
283  * @param style: format string
284  * @param pad: whether to pad field width
285  * @returns: number of printed characters excluding trailing '\0'.
286  */
287 int snprint_foreign_paths(char *buf, int len, const char *style, int pad);
288
289 /**
290  * snprint_foreign_multipaths(buf, len, style, pad);
291  * prints formatted map information from foreign libraries into buffer,
292  * '\0' - terminated.
293  * @param buf: output buffer
294  * @param len: size of output buffer
295  * @param style: format string
296  * @param pad: whether to pad field width
297  * @returns: number of printed characters excluding trailing '\0'.
298  */
299 int snprint_foreign_multipaths(char *buf, int len,
300                                const char *style, int pretty);
301
302 /**
303  * print_foreign_topology(v)
304  * print foreign topology to stdout
305  * @param verbosity: verbosity level
306  */
307 void print_foreign_topology(int verbosity);
308
309 /**
310  * is_claimed_by_foreign(ud)
311  * @param udev: udev device
312  * @returns: true if device is (newly or already) claimed by a foreign lib
313  */
314 static inline bool
315 is_claimed_by_foreign(struct udev_device *ud)
316 {
317         int rc = add_foreign(ud);
318
319         return (rc == FOREIGN_CLAIMED || rc == FOREIGN_OK);
320 }
321
322 #endif /*  _FOREIGN_H */