4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU Lesser General Public License as
8 * published by the Free Software Foundation; either version 2.1 of the
9 * License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
21 * Copyright (c) 2014, 2017, Intel Corporation.
24 * Amir Shehata <amir.shehata@intel.com>
27 #ifndef LIB_LNET_CONFIG_API_H
28 #define LIB_LNET_CONFIG_API_H
31 #include <libcfs/util/string.h>
32 #include <linux/lnet/lnet-dlc.h>
33 #include <linux/lnet/nidstr.h>
35 #define LUSTRE_CFG_RC_NO_ERR 0
36 #define LUSTRE_CFG_RC_BAD_PARAM -1
37 #define LUSTRE_CFG_RC_MISSING_PARAM -2
38 #define LUSTRE_CFG_RC_OUT_OF_RANGE_PARAM -3
39 #define LUSTRE_CFG_RC_OUT_OF_MEM -4
40 #define LUSTRE_CFG_RC_GENERIC_ERR -5
41 #define LUSTRE_CFG_RC_NO_MATCH -6
42 #define LUSTRE_CFG_RC_MATCH -7
43 #define LUSTRE_CFG_RC_SKIP -8
44 #define LUSTRE_CFG_RC_LAST_ELEM -9
47 LNETCTL_CONFIG_CMD = 1,
48 LNETCTL_UNCONFIG_CMD = 2,
53 LNETCTL_MANAGE_CMD = 7,
57 struct lnet_dlc_network_descr {
58 struct list_head network_on_rule;
60 struct list_head nw_intflist;
63 struct lnet_dlc_intf_descr {
64 struct list_head intf_on_network;
65 char intf_name[IFNAMSIZ];
66 struct cfs_expr_list *cpt_expr;
69 /* forward declaration of the cYAML structure. */
73 * lustre_lnet_config_lib_init()
74 * Initialize the Library to enable communication with the LNET kernel
75 * module. Returns the device ID or -EINVAL if there is an error
77 int lustre_lnet_config_lib_init();
80 * lustre_lnet_config_lib_uninit
81 * Uninitialize the DLC Library
83 void lustre_lnet_config_lib_uninit();
86 * lustre_lnet_config_ni_system
87 * Initialize/Uninitialize the lnet NI system.
89 * up - whehter to init or uninit the system
90 * load_ni_from_mod - load NI from mod params.
91 * seq_no - sequence number of the request
92 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
95 int lustre_lnet_config_ni_system(bool up, bool load_ni_from_mod,
96 int seq_no, struct cYAML **err_rc);
99 * lustre_lnet_config_route
100 * Send down an IOCTL to the kernel to configure the route
104 * hops - number of hops passed down by the user
105 * prio - priority of the route
106 * sen - health sensitivity value for the gateway
107 * seq_no - sequence number of the request
108 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
110 int lustre_lnet_config_route(char *nw, char *gw, int hops, int prio,
111 int sen, int seq_no, struct cYAML **err_rc);
114 * lustre_lnet_del_route
115 * Send down an IOCTL to the kernel to delete a route
119 * seq_no - sequence number of the request
120 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
122 int lustre_lnet_del_route(char *nw, char *gw, int seq_no,
123 struct cYAML **err_rc);
126 * lustre_lnet_show_route
127 * Send down an IOCTL to the kernel to show routes
128 * This function will get one route at a time and filter according to
129 * provided parameters. If no routes are available then it will dump all
130 * routes that are in the system.
132 * nw - network. Optional. Used to filter output
133 * gw - gateway. Optional. Used to filter ouptut
134 * hops - number of hops passed down by the user
135 * Optional. Used to filter output.
136 * prio - priority of the route. Optional. Used to filter output.
137 * detail - flag to indicate whether detail output is required
138 * seq_no - sequence number of the request
139 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
140 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
141 * backup - true to output only what's necessary for reconfiguring
144 int lustre_lnet_show_route(char *nw, char *gw,
145 int hops, int prio, int detail,
146 int seq_no, struct cYAML **show_rc,
147 struct cYAML **err_rc, bool backup);
150 * lustre_lnet_config_ni
151 * Send down an IOCTL to configure a network interface. It implicitly
152 * creates a network if one doesn't exist..
154 * nw_descr - network and interface descriptor
155 * global_cpts - globally defined CPTs
156 * ip2net - this parameter allows configuring multiple networks.
157 * it takes precedence over the net and intf parameters
158 * tunables - LND tunables
159 * seq_no - sequence number of the request
160 * lnd_tunables - lnet specific tunable parameters
161 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
163 int lustre_lnet_config_ni(struct lnet_dlc_network_descr *nw_descr,
164 struct cfs_expr_list *global_cpts,
166 struct lnet_ioctl_config_lnd_tunables *tunables,
167 int seq_no, struct cYAML **err_rc);
171 * Send down an IOCTL to delete a network interface. It implicitly
172 * deletes a network if it becomes empty of nis
174 * nw - network and interface list
175 * seq_no - sequence number of the request
176 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
178 int lustre_lnet_del_ni(struct lnet_dlc_network_descr *nw,
179 int seq_no, struct cYAML **err_rc);
182 * lustre_lnet_show_net
183 * Send down an IOCTL to show networks.
184 * This function will use the nw paramter to filter the output. If it's
185 * not provided then all networks are listed.
187 * nw - network to show. Optional. Used to filter output.
188 * detail - flag to indicate if we require detail output.
189 * seq_no - sequence number of the request
190 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
191 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
192 * backup - true to output only what's necessary for reconfiguring
195 int lustre_lnet_show_net(char *nw, int detail, int seq_no,
196 struct cYAML **show_rc, struct cYAML **err_rc,
200 * lustre_lnet_enable_routing
201 * Send down an IOCTL to enable or diable routing
203 * enable - 1 to enable routing, 0 to disable routing
204 * seq_no - sequence number of the request
205 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
207 int lustre_lnet_enable_routing(int enable, int seq_no,
208 struct cYAML **err_rc);
211 * lustre_lnet_config_numa_range
212 * Set the NUMA range which impacts the NIs to be selected
213 * during sending. If the NUMA range is large the NUMA
214 * distance between the message memory and the NI becomes
215 * less significant. The NUMA range is a relative number
216 * with no other meaning besides allowing a wider breadth
217 * for picking an NI to send from.
219 * range - numa range value.
220 * seq_no - sequence number of the request
221 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
224 int lustre_lnet_config_numa_range(int range, int seq_no,
225 struct cYAML **err_rc);
228 * lustre_lnet_show_num_range
229 * Get the currently set NUMA range
231 * seq_no - sequence number of the request
232 * show_rc - [OUT] struct cYAML tree containing NUMA range info
233 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
236 int lustre_lnet_show_numa_range(int seq_no, struct cYAML **show_rc,
237 struct cYAML **err_rc);
240 * lustre_lnet_config_ni_healthv
241 * set the health value of the NI. -1 resets the value to maximum.
243 * value: health value to set.
244 * all: true to set all local NIs to that value.
245 * ni_nid: NI NID to set its health value. all parameter always takes
247 * seq_no - sequence number of the request
248 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
251 int lustre_lnet_config_ni_healthv(int value, bool all, char *ni_nid,
252 int seq_no, struct cYAML **err_rc);
255 * lustre_lnet_config_peer_ni_healthv
256 * set the health value of the peer NI. -1 resets the value to maximum.
258 * value: health value to set.
259 * all: true to set all local NIs to that value.
260 * pni_nid: Peer NI NID to set its health value. all parameter always takes
262 * seq_no - sequence number of the request
263 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
266 int lustre_lnet_config_peer_ni_healthv(int value, bool all, char *pni_nid,
267 int seq_no, struct cYAML **err_rc);
270 * lustre_lnet_config_recov_intrv
271 * set the recovery interval in seconds. That's the interval to ping an
272 * unhealthy interface.
274 * intrv - recovery interval value to configure
275 * seq_no - sequence number of the request
276 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
279 int lustre_lnet_config_recov_intrv(int intrv, int seq_no, struct cYAML **err_rc);
282 * lustre_lnet_show_recov_intrv
283 * show the recovery interval set in the system
285 * seq_no - sequence number of the request
286 * show_rc - [OUT] struct cYAML tree containing health sensitivity info
287 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
290 int lustre_lnet_show_recov_intrv(int seq_no, struct cYAML **show_rc,
291 struct cYAML **err_rc);
294 * lustre_lnet_config_rtr_sensitivity
295 * sets the router sensitivity percentage. If the percentage health
296 * of a router interface drops below that it's considered failed
298 * sen - sensitivity value to configure
299 * seq_no - sequence number of the request
300 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
303 int lustre_lnet_config_rtr_sensitivity(int sen, int seq_no, struct cYAML **err_rc);
306 * lustre_lnet_config_hsensitivity
307 * sets the health sensitivity; the value by which to decrement the
308 * health value of a local or peer NI. If 0 then health is turned off
310 * sen - sensitivity value to configure
311 * seq_no - sequence number of the request
312 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
315 int lustre_lnet_config_hsensitivity(int sen, int seq_no, struct cYAML **err_rc);
318 * lustre_lnet_show_hsensitivity
319 * show the health sensitivity in the system
321 * seq_no - sequence number of the request
322 * show_rc - [OUT] struct cYAML tree containing health sensitivity info
323 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
326 int lustre_lnet_show_hsensitivity(int seq_no, struct cYAML **show_rc,
327 struct cYAML **err_rc);
330 * lustre_lnet_show_rtr_sensitivity
331 * show the router sensitivity percentage in the system
333 * seq_no - sequence number of the request
334 * show_rc - [OUT] struct cYAML tree containing health sensitivity info
335 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
338 int lustre_lnet_show_rtr_sensitivity(int seq_no, struct cYAML **show_rc,
339 struct cYAML **err_rc);
342 * lustre_lnet_config_transaction_to
343 * sets the timeout after which a message expires or a timeout event is
344 * propagated for an expired response.
346 * timeout - timeout value to configure
347 * seq_no - sequence number of the request
348 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
351 int lustre_lnet_config_transaction_to(int timeout, int seq_no, struct cYAML **err_rc);
354 * lustre_lnet_show_transaction_to
355 * show the transaction timeout in the system
357 * seq_no - sequence number of the request
358 * show_rc - [OUT] struct cYAML tree containing transaction timeout info
359 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
362 int lustre_lnet_show_transaction_to(int seq_no, struct cYAML **show_rc,
363 struct cYAML **err_rc);
366 * lustre_lnet_config_retry_count
367 * sets the maximum number of retries to resend a message
369 * count - maximum value to configure
370 * seq_no - sequence number of the request
371 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
374 int lustre_lnet_config_retry_count(int count, int seq_no, struct cYAML **err_rc);
377 * lustre_lnet_show_retry_count
378 * show current maximum number of retries in the system
380 * seq_no - sequence number of the request
381 * show_rc - [OUT] struct cYAML tree containing retry count info
382 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
385 int lustre_lnet_show_retry_count(int seq_no, struct cYAML **show_rc,
386 struct cYAML **err_rc);
388 int lustre_lnet_show_local_ni_recovq(int seq_no, struct cYAML **show_rc,
389 struct cYAML **err_rc);
391 int lustre_lnet_show_peer_ni_recovq(int seq_no, struct cYAML **show_rc,
392 struct cYAML **err_rc);
395 * lustre_lnet_config_max_intf
396 * Sets the maximum number of interfaces per node. this tunable is
397 * primarily useful for sanity checks prior to allocating memory.
399 * max - maximum value to configure
400 * seq_no - sequence number of the request
401 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
404 int lustre_lnet_config_max_intf(int max, int seq_no, struct cYAML **err_rc);
407 * lustre_lnet_show_max_intf
408 * show current maximum interface setting
410 * seq_no - sequence number of the request
411 * show_rc - [OUT] struct cYAML tree containing NUMA range info
412 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
415 int lustre_lnet_show_max_intf(int seq_no, struct cYAML **show_rc,
416 struct cYAML **err_rc);
419 * lustre_lnet_config_discovery
420 * Enable or disable peer discovery. Peer discovery is enabled by default.
422 * enable - non-0 enables, 0 disables
423 * seq_no - sequence number of the request
424 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
427 int lustre_lnet_config_discovery(int enable, int seq_no, struct cYAML **err_rc);
430 * lustre_lnet_show_discovery
431 * show current peer discovery setting
433 * seq_no - sequence number of the request
434 * show_rc - [OUT] struct cYAML tree containing NUMA range info
435 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
438 int lustre_lnet_show_discovery(int seq_no, struct cYAML **show_rc,
439 struct cYAML **err_rc);
442 * lustre_lnet_config_drop_asym_route
443 * Drop or accept asymmetrical route messages. Accept by default.
445 * drop - non-0 drops, 0 accepts
446 * seq_no - sequence number of the request
447 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
450 int lustre_lnet_config_drop_asym_route(int drop, int seq_no,
451 struct cYAML **err_rc);
454 * lustre_lnet_show_drop_asym_route
455 * show current drop asym route setting
457 * seq_no - sequence number of the request
458 * show_rc - [OUT] struct cYAML tree containing NUMA range info
459 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
462 int lustre_lnet_show_drop_asym_route(int seq_no, struct cYAML **show_rc,
463 struct cYAML **err_rc);
466 * lustre_lnet_config_buffers
467 * Send down an IOCTL to configure routing buffer sizes. A value of 0 means
468 * default that particular buffer to default size. A value of -1 means
469 * leave the value of the buffer un changed.
471 * tiny - tiny buffers
472 * small - small buffers
473 * large - large buffers.
474 * seq_no - sequence number of the request
475 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
477 int lustre_lnet_config_buffers(int tiny, int small, int large,
478 int seq_no, struct cYAML **err_rc);
481 * lustre_lnet_show_routing
482 * Send down an IOCTL to dump buffers and routing status
483 * This function is used to dump buffers for all CPU partitions.
485 * seq_no - sequence number of the request
486 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
487 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
488 * backup - true to output only what's necessary for reconfiguring
491 int lustre_lnet_show_routing(int seq_no, struct cYAML **show_rc,
492 struct cYAML **err_rc, bool backup);
495 * lustre_lnet_show_stats
496 * Shows internal LNET statistics. This is useful to display the
497 * current LNET activity, such as number of messages route, etc
499 * seq_no - sequence number of the command
500 * show_rc - YAML structure of the resultant show
501 * err_rc - YAML strucutre of the resultant return code.
503 int lustre_lnet_show_stats(int seq_no, struct cYAML **show_rc,
504 struct cYAML **err_rc);
507 * lustre_lnet_config_peer_nid
508 * Add a peer nid to a peer with primary nid pnid. If no pnid is given
509 * then the first nid in the nid list becomes the primary nid for
510 * a newly created peer.
511 * Otherwise if pnid is provided and it's unique then a new peer is
512 * created with pnid as the primary NID and the nids in the nid list as
514 * If any of the peers nids provided in with exception to the pnid is
515 * not unique the operation fails. Some peer nids might have already
516 * been added. It's the role of the caller of this API to remove the
517 * added NIDs if they wish.
519 * pnid - Primary NID of the peer
520 * nid - list of nids to add
521 * num_nids - number of nids in the nid array
522 * mr - true if this peer is MR capable.
523 * ip2nets - true if a list of nid expressions are given to configure
525 * seq_no - sequence number of the command
526 * err_rc - YAML strucutre of the resultant return code.
528 int lustre_lnet_config_peer_nid(char *pnid, char **nid, int num_nids,
529 bool mr, bool ip2nets, int seq_no,
530 struct cYAML **err_rc);
533 * lustre_lnet_del_peer_nid
534 * Delete the nids given in the nid list from the peer with primary NID
535 * pnid. If pnid is NULL or it doesn't identify a peer the operation
536 * fails and no change happens to the system.
537 * The operation is aborted on the first NID that fails to be deleted.
539 * pnid - Primary NID of the peer
540 * nid - list of nids to add
541 * num_nids - number of nids in the nid array
542 * ip2nets - used to specify a range of nids
543 * seq_no - sequence number of the command
544 * err_rc - YAML strucutre of the resultant return code.
546 int lustre_lnet_del_peer_nid(char *pnid, char **nid, int num_nids,
547 bool ip2nets, int seq_no, struct cYAML **err_rc);
550 * lustre_lnet_show_peer
551 * Show the peer identified by nid, knid. If knid is NULL all
552 * peers in the system are shown.
554 * knid - A NID of the peer
555 * detail - display detailed information
556 * seq_no - sequence number of the command
557 * show_rc - YAML structure of the resultant show
558 * err_rc - YAML strucutre of the resultant return code.
559 * backup - true to output only what's necessary for reconfiguring
563 int lustre_lnet_show_peer(char *knid, int detail, int seq_no,
564 struct cYAML **show_rc, struct cYAML **err_rc,
568 * lustre_lnet_list_peer
569 * List the known peers.
571 * seq_no - sequence number of the command
572 * show_rc - YAML structure of the resultant show
573 * err_rc - YAML strucutre of the resultant return code.
576 int lustre_lnet_list_peer(int seq_no,
577 struct cYAML **show_rc, struct cYAML **err_rc);
579 /* lustre_lnet_ping_nid
580 * Ping the nid list, pnids.
582 * pnids - NID list to ping.
583 * timeout - timeout(seconds) for ping.
584 * seq_no - sequence number of the command.
585 * show_rc - YAML structure of the resultant show.
586 * err_rc - YAML strucutre of the resultant return code.
589 int lustre_lnet_ping_nid(char *pnid, int timeout, int seq_no,
590 struct cYAML **show_rc, struct cYAML **err_rc);
592 /* lustre_lnet_discover_nid
593 * Discover the nid list, pnids.
595 * pnids - NID list to discover.
596 * force - force discovery.
597 * seq_no - sequence number of the command.
598 * show_rc - YAML structure of the resultant show.
599 * err_rc - YAML strucutre of the resultant return code.
602 int lustre_lnet_discover_nid(char *pnid, int force, int seq_no,
603 struct cYAML **show_rc, struct cYAML **err_rc);
607 * Parses the provided YAML file and then calls the specific APIs
608 * to configure the entities identified in the file
611 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
613 int lustre_yaml_config(char *f, struct cYAML **err_rc);
617 * Parses the provided YAML file and then calls the specific APIs
618 * to delete the entities identified in the file
621 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
623 int lustre_yaml_del(char *f, struct cYAML **err_rc);
627 * Parses the provided YAML file and then calls the specific APIs
628 * to show the entities identified in the file
631 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
632 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
634 int lustre_yaml_show(char *f, struct cYAML **show_rc,
635 struct cYAML **err_rc);
639 * Parses the provided YAML file and then calls the specific APIs
640 * to execute the entities identified in the file
643 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
644 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
646 int lustre_yaml_exec(char *f, struct cYAML **show_rc,
647 struct cYAML **err_rc);
650 * lustre_lnet_init_nw_descr
651 * initialize the network descriptor structure for use
653 void lustre_lnet_init_nw_descr(struct lnet_dlc_network_descr *nw_descr);
656 * lustre_lnet_parse_interfaces
657 * prase an interface string and populate descriptor structures
658 * intf_str - interface string of the format
659 * <intf>[<expr>], <intf>[<expr>],..
660 * nw_descr - network descriptor to populate
661 * init - True to initialize nw_descr
663 int lustre_lnet_parse_interfaces(char *intf_str,
664 struct lnet_dlc_network_descr *nw_descr);
667 * lustre_lnet_parse_nidstr
668 * This is a small wrapper around cfs_parse_nidlist.
669 * nidstr - A string parseable by cfs_parse_nidlist
670 * lnet_nidlist - An array of lnet_nid_t to hold the nids specified
672 * max_nids - Size of the lnet_nidlist array, and the maximum number of
673 * nids that can be expressed by the nidstring. If the
674 * nidstring expands to a larger number of nids than max_nids
675 * then an error is returned.
676 * err_str - char pointer where we store an informative error
677 * message when an error is encountered
679 * The number (> 0) of lnet_nid_t stored in the supplied array, or
680 * LUSTRE_CFG_RC_BAD_PARAM if:
682 * - nidstr contains an asterisk. This character is not allowed
683 * because it would cause the size of the expanded nidlist to exceed
684 * the maximum number of nids that is supported by expected callers
686 * - cfs_parse_nidlist fails to parse the nidstring
687 * - The nidlist populated by cfs_parse_nidlist is empty
688 * - The nidstring expands to a larger number of nids than max_nids
689 * - The nidstring expands to zero nids
690 * LUSTRE_CFG_RC_OUT_OF_MEM if:
691 * - cfs_expand_nidlist can return ENOMEM. We return out of mem in
694 int lustre_lnet_parse_nidstr(char *nidstr, lnet_nid_t *lnet_nidlist,
695 int max_nids, char *err_str);
698 * lustre_lnet_parse_nids
699 * Parse a set of nids into a locally allocated array and return the
700 * pointer of the array to the caller. The caller is responsible for
701 * freeing the array. If an initial array is provided then copy over
702 * the contents of that array into the new array and append to it the
704 * The nids can be of the form "nid [,nid, nid, nid]"
705 * nids: nids string to be parsed
706 * array: initial array of content
707 * size: num of elements in the array
708 * out_array: [OUT] new allocated array.
709 * Returns size of array
710 * sets the out_array to NULL on failure.
712 int lustre_lnet_parse_nids(char *nids, char **array, int size,
715 #endif /* LIB_LNET_CONFIG_API_H */