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. */
72 int tokenize_nidstr(char *nidstr, char *out[LNET_MAX_STR_LEN], char *err_str);
75 * lustre_lnet_config_lib_init()
76 * Initialize the Library to enable communication with the LNET kernel
77 * module. Returns the device ID or -EINVAL if there is an error
79 int lustre_lnet_config_lib_init();
82 * lustre_lnet_config_lib_uninit
83 * Uninitialize the DLC Library
85 void lustre_lnet_config_lib_uninit();
88 * lustre_lnet_config_ni_system
89 * Initialize/Uninitialize the lnet NI system.
91 * up - whehter to init or uninit the system
92 * load_ni_from_mod - load NI from mod params.
93 * seq_no - sequence number of the request
94 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
97 int lustre_lnet_config_ni_system(bool up, bool load_ni_from_mod,
98 int seq_no, struct cYAML **err_rc);
101 * lustre_lnet_config_route
102 * Send down an IOCTL to the kernel to configure the route
106 * hops - number of hops passed down by the user
107 * prio - priority of the route
108 * sen - health sensitivity value for the gateway
109 * seq_no - sequence number of the request
110 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
112 int lustre_lnet_config_route(char *nw, char *gw, int hops, int prio,
113 int sen, int seq_no, struct cYAML **err_rc);
116 * lustre_lnet_del_route
117 * Send down an IOCTL to the kernel to delete a route
121 * seq_no - sequence number of the request
122 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
124 int lustre_lnet_del_route(char *nw, char *gw, int seq_no,
125 struct cYAML **err_rc);
128 * lustre_lnet_show_route
129 * Send down an IOCTL to the kernel to show routes
130 * This function will get one route at a time and filter according to
131 * provided parameters. If no routes are available then it will dump all
132 * routes that are in the system.
134 * nw - network. Optional. Used to filter output
135 * gw - gateway. Optional. Used to filter ouptut
136 * hops - number of hops passed down by the user
137 * Optional. Used to filter output.
138 * prio - priority of the route. Optional. Used to filter output.
139 * detail - flag to indicate whether detail output is required
140 * seq_no - sequence number of the request
141 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
142 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
143 * backup - true to output only what's necessary for reconfiguring
146 int lustre_lnet_show_route(char *nw, char *gw,
147 int hops, int prio, int detail,
148 int seq_no, struct cYAML **show_rc,
149 struct cYAML **err_rc, bool backup);
152 * lustre_lnet_config_ni
153 * Send down an IOCTL to configure a network interface. It implicitly
154 * creates a network if one doesn't exist..
156 * nw_descr - network and interface descriptor
157 * global_cpts - globally defined CPTs
158 * ip2net - this parameter allows configuring multiple networks.
159 * it takes precedence over the net and intf parameters
160 * tunables - LND tunables
161 * seq_no - sequence number of the request
162 * lnd_tunables - lnet specific tunable parameters
163 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
165 int lustre_lnet_config_ni(struct lnet_dlc_network_descr *nw_descr,
166 struct cfs_expr_list *global_cpts,
168 struct lnet_ioctl_config_lnd_tunables *tunables,
169 int seq_no, struct cYAML **err_rc);
173 * Send down an IOCTL to delete a network interface. It implicitly
174 * deletes a network if it becomes empty of nis
176 * nw - network and interface list
177 * seq_no - sequence number of the request
178 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
180 int lustre_lnet_del_ni(struct lnet_dlc_network_descr *nw,
181 int seq_no, struct cYAML **err_rc);
184 * lustre_lnet_show_net
185 * Send down an IOCTL to show networks.
186 * This function will use the nw paramter to filter the output. If it's
187 * not provided then all networks are listed.
189 * nw - network to show. Optional. Used to filter output.
190 * detail - flag to indicate if we require detail output.
191 * seq_no - sequence number of the request
192 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
193 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
194 * backup - true to output only what's necessary for reconfiguring
197 int lustre_lnet_show_net(char *nw, int detail, int seq_no,
198 struct cYAML **show_rc, struct cYAML **err_rc,
202 * lustre_lnet_enable_routing
203 * Send down an IOCTL to enable or diable routing
205 * enable - 1 to enable routing, 0 to disable routing
206 * seq_no - sequence number of the request
207 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
209 int lustre_lnet_enable_routing(int enable, int seq_no,
210 struct cYAML **err_rc);
213 * lustre_lnet_config_numa_range
214 * Set the NUMA range which impacts the NIs to be selected
215 * during sending. If the NUMA range is large the NUMA
216 * distance between the message memory and the NI becomes
217 * less significant. The NUMA range is a relative number
218 * with no other meaning besides allowing a wider breadth
219 * for picking an NI to send from.
221 * range - numa range value.
222 * seq_no - sequence number of the request
223 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
226 int lustre_lnet_config_numa_range(int range, int seq_no,
227 struct cYAML **err_rc);
230 * lustre_lnet_show_num_range
231 * Get the currently set NUMA range
233 * seq_no - sequence number of the request
234 * show_rc - [OUT] struct cYAML tree containing NUMA range info
235 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
238 int lustre_lnet_show_numa_range(int seq_no, struct cYAML **show_rc,
239 struct cYAML **err_rc);
242 * lustre_lnet_config_ni_healthv
243 * set the health value of the NI. -1 resets the value to maximum.
245 * value: health value to set.
246 * all: true to set all local NIs to that value.
247 * ni_nid: NI NID to set its health value. all parameter always takes
249 * seq_no - sequence number of the request
250 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
253 int lustre_lnet_config_ni_healthv(int value, bool all, char *ni_nid,
254 int seq_no, struct cYAML **err_rc);
257 * lustre_lnet_config_peer_ni_healthv
258 * set the health value of the peer NI. -1 resets the value to maximum.
260 * value: health value to set.
261 * all: true to set all local NIs to that value.
262 * pni_nid: Peer NI NID to set its health value. all parameter always takes
264 * seq_no - sequence number of the request
265 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
268 int lustre_lnet_config_peer_ni_healthv(int value, bool all, char *pni_nid,
269 int seq_no, struct cYAML **err_rc);
272 * lustre_lnet_config_recov_intrv
273 * set the recovery interval in seconds. That's the interval to ping an
274 * unhealthy interface.
276 * intrv - recovery interval value to configure
277 * seq_no - sequence number of the request
278 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
281 int lustre_lnet_config_recov_intrv(int intrv, int seq_no, struct cYAML **err_rc);
284 * lustre_lnet_show_recov_intrv
285 * show the recovery interval set in the system
287 * seq_no - sequence number of the request
288 * show_rc - [OUT] struct cYAML tree containing health sensitivity info
289 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
292 int lustre_lnet_show_recov_intrv(int seq_no, struct cYAML **show_rc,
293 struct cYAML **err_rc);
296 * lustre_lnet_config_rtr_sensitivity
297 * sets the router sensitivity percentage. If the percentage health
298 * of a router interface drops below that it's considered failed
300 * sen - sensitivity value to configure
301 * seq_no - sequence number of the request
302 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
305 int lustre_lnet_config_rtr_sensitivity(int sen, int seq_no, struct cYAML **err_rc);
308 * lustre_lnet_config_hsensitivity
309 * sets the health sensitivity; the value by which to decrement the
310 * health value of a local or peer NI. If 0 then health is turned off
312 * sen - sensitivity value to configure
313 * seq_no - sequence number of the request
314 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
317 int lustre_lnet_config_hsensitivity(int sen, int seq_no, struct cYAML **err_rc);
320 * lustre_lnet_show_hsensitivity
321 * show the health sensitivity in the system
323 * seq_no - sequence number of the request
324 * show_rc - [OUT] struct cYAML tree containing health sensitivity info
325 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
328 int lustre_lnet_show_hsensitivity(int seq_no, struct cYAML **show_rc,
329 struct cYAML **err_rc);
332 * lustre_lnet_show_rtr_sensitivity
333 * show the router sensitivity percentage in the system
335 * seq_no - sequence number of the request
336 * show_rc - [OUT] struct cYAML tree containing health sensitivity info
337 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
340 int lustre_lnet_show_rtr_sensitivity(int seq_no, struct cYAML **show_rc,
341 struct cYAML **err_rc);
344 * lustre_lnet_config_transaction_to
345 * sets the timeout after which a message expires or a timeout event is
346 * propagated for an expired response.
348 * timeout - timeout value to configure
349 * seq_no - sequence number of the request
350 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
353 int lustre_lnet_config_transaction_to(int timeout, int seq_no, struct cYAML **err_rc);
356 * lustre_lnet_show_transaction_to
357 * show the transaction timeout in the system
359 * seq_no - sequence number of the request
360 * show_rc - [OUT] struct cYAML tree containing transaction timeout info
361 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
364 int lustre_lnet_show_transaction_to(int seq_no, struct cYAML **show_rc,
365 struct cYAML **err_rc);
368 * lustre_lnet_config_retry_count
369 * sets the maximum number of retries to resend a message
371 * count - maximum value to configure
372 * seq_no - sequence number of the request
373 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
376 int lustre_lnet_config_retry_count(int count, int seq_no, struct cYAML **err_rc);
379 * lustre_lnet_show_retry_count
380 * show current maximum number of retries in the system
382 * seq_no - sequence number of the request
383 * show_rc - [OUT] struct cYAML tree containing retry count info
384 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
387 int lustre_lnet_show_retry_count(int seq_no, struct cYAML **show_rc,
388 struct cYAML **err_rc);
390 int lustre_lnet_show_local_ni_recovq(int seq_no, struct cYAML **show_rc,
391 struct cYAML **err_rc);
393 int lustre_lnet_show_peer_ni_recovq(int seq_no, struct cYAML **show_rc,
394 struct cYAML **err_rc);
397 * lustre_lnet_config_max_intf
398 * Sets the maximum number of interfaces per node. this tunable is
399 * primarily useful for sanity checks prior to allocating memory.
401 * max - maximum value to configure
402 * seq_no - sequence number of the request
403 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
406 int lustre_lnet_config_max_intf(int max, int seq_no, struct cYAML **err_rc);
409 * lustre_lnet_show_max_intf
410 * show current maximum interface setting
412 * seq_no - sequence number of the request
413 * show_rc - [OUT] struct cYAML tree containing NUMA range info
414 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
417 int lustre_lnet_show_max_intf(int seq_no, struct cYAML **show_rc,
418 struct cYAML **err_rc);
421 * lustre_lnet_config_discovery
422 * Enable or disable peer discovery. Peer discovery is enabled by default.
424 * enable - non-0 enables, 0 disables
425 * seq_no - sequence number of the request
426 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
429 int lustre_lnet_config_discovery(int enable, int seq_no, struct cYAML **err_rc);
432 * lustre_lnet_show_discovery
433 * show current peer discovery setting
435 * seq_no - sequence number of the request
436 * show_rc - [OUT] struct cYAML tree containing NUMA range info
437 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
440 int lustre_lnet_show_discovery(int seq_no, struct cYAML **show_rc,
441 struct cYAML **err_rc);
444 * lustre_lnet_config_drop_asym_route
445 * Drop or accept asymmetrical route messages. Accept by default.
447 * drop - non-0 drops, 0 accepts
448 * seq_no - sequence number of the request
449 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
452 int lustre_lnet_config_drop_asym_route(int drop, int seq_no,
453 struct cYAML **err_rc);
456 * lustre_lnet_show_drop_asym_route
457 * show current drop asym route setting
459 * seq_no - sequence number of the request
460 * show_rc - [OUT] struct cYAML tree containing NUMA range info
461 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
464 int lustre_lnet_show_drop_asym_route(int seq_no, struct cYAML **show_rc,
465 struct cYAML **err_rc);
468 * lustre_lnet_config_buffers
469 * Send down an IOCTL to configure routing buffer sizes. A value of 0 means
470 * default that particular buffer to default size. A value of -1 means
471 * leave the value of the buffer un changed.
473 * tiny - tiny buffers
474 * small - small buffers
475 * large - large buffers.
476 * seq_no - sequence number of the request
477 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
479 int lustre_lnet_config_buffers(int tiny, int small, int large,
480 int seq_no, struct cYAML **err_rc);
483 * lustre_lnet_show_routing
484 * Send down an IOCTL to dump buffers and routing status
485 * This function is used to dump buffers for all CPU partitions.
487 * seq_no - sequence number of the request
488 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
489 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
490 * backup - true to output only what's necessary for reconfiguring
493 int lustre_lnet_show_routing(int seq_no, struct cYAML **show_rc,
494 struct cYAML **err_rc, bool backup);
497 * lustre_lnet_show_stats
498 * Shows internal LNET statistics. This is useful to display the
499 * current LNET activity, such as number of messages route, etc
501 * seq_no - sequence number of the command
502 * show_rc - YAML structure of the resultant show
503 * err_rc - YAML strucutre of the resultant return code.
505 int lustre_lnet_show_stats(int seq_no, struct cYAML **show_rc,
506 struct cYAML **err_rc);
509 * lustre_lnet_config_peer_nid
510 * Add a peer nid to a peer with primary nid pnid. If no pnid is given
511 * then the first nid in the nid list becomes the primary nid for
512 * a newly created peer.
513 * Otherwise if pnid is provided and it's unique then a new peer is
514 * created with pnid as the primary NID and the nids in the nid list as
516 * If any of the peers nids provided in with exception to the pnid is
517 * not unique the operation fails. Some peer nids might have already
518 * been added. It's the role of the caller of this API to remove the
519 * added NIDs if they wish.
521 * pnid - Primary NID of the peer
522 * nid - list of nids to add
523 * num_nids - number of nids in the nid array
524 * mr - true if this peer is MR capable.
525 * ip2nets - true if a list of nid expressions are given to configure
527 * seq_no - sequence number of the command
528 * err_rc - YAML strucutre of the resultant return code.
530 int lustre_lnet_config_peer_nid(char *pnid, char **nid, int num_nids,
531 bool mr, bool ip2nets, int seq_no,
532 struct cYAML **err_rc);
535 * lustre_lnet_del_peer_nid
536 * Delete the nids given in the nid list from the peer with primary NID
537 * pnid. If pnid is NULL or it doesn't identify a peer the operation
538 * fails and no change happens to the system.
539 * The operation is aborted on the first NID that fails to be deleted.
541 * pnid - Primary NID of the peer
542 * nid - list of nids to add
543 * num_nids - number of nids in the nid array
544 * ip2nets - used to specify a range of nids
545 * seq_no - sequence number of the command
546 * err_rc - YAML strucutre of the resultant return code.
548 int lustre_lnet_del_peer_nid(char *pnid, char **nid, int num_nids,
549 bool ip2nets, int seq_no, struct cYAML **err_rc);
552 * lustre_lnet_show_peer
553 * Show the peer identified by nid, knid. If knid is NULL all
554 * peers in the system are shown.
556 * knid - A NID of the peer
557 * detail - display detailed information
558 * seq_no - sequence number of the command
559 * show_rc - YAML structure of the resultant show
560 * err_rc - YAML strucutre of the resultant return code.
561 * backup - true to output only what's necessary for reconfiguring
565 int lustre_lnet_show_peer(char *knid, int detail, int seq_no,
566 struct cYAML **show_rc, struct cYAML **err_rc,
570 * lustre_lnet_list_peer
571 * List the known peers.
573 * seq_no - sequence number of the command
574 * show_rc - YAML structure of the resultant show
575 * err_rc - YAML strucutre of the resultant return code.
578 int lustre_lnet_list_peer(int seq_no,
579 struct cYAML **show_rc, struct cYAML **err_rc);
581 /* lustre_lnet_ping_nid
582 * Ping the nid list, pnids.
584 * pnids - NID list to ping.
585 * timeout - timeout(seconds) for ping.
586 * seq_no - sequence number of the command.
587 * show_rc - YAML structure of the resultant show.
588 * err_rc - YAML strucutre of the resultant return code.
591 int lustre_lnet_ping_nid(char *pnid, int timeout, int seq_no,
592 struct cYAML **show_rc, struct cYAML **err_rc);
594 /* lustre_lnet_discover_nid
595 * Discover the nid list, pnids.
597 * pnids - NID list to discover.
598 * force - force discovery.
599 * seq_no - sequence number of the command.
600 * show_rc - YAML structure of the resultant show.
601 * err_rc - YAML strucutre of the resultant return code.
604 int lustre_lnet_discover_nid(char *pnid, int force, int seq_no,
605 struct cYAML **show_rc, struct cYAML **err_rc);
609 * Parses the provided YAML file and then calls the specific APIs
610 * to configure the entities identified in the file
613 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
615 int lustre_yaml_config(char *f, struct cYAML **err_rc);
619 * Parses the provided YAML file and then calls the specific APIs
620 * to delete the entities identified in the file
623 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
625 int lustre_yaml_del(char *f, struct cYAML **err_rc);
629 * Parses the provided YAML file and then calls the specific APIs
630 * to show the entities identified in the file
633 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
634 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
636 int lustre_yaml_show(char *f, struct cYAML **show_rc,
637 struct cYAML **err_rc);
641 * Parses the provided YAML file and then calls the specific APIs
642 * to execute the entities identified in the file
645 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
646 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
648 int lustre_yaml_exec(char *f, struct cYAML **show_rc,
649 struct cYAML **err_rc);
652 * lustre_lnet_init_nw_descr
653 * initialize the network descriptor structure for use
655 void lustre_lnet_init_nw_descr(struct lnet_dlc_network_descr *nw_descr);
658 * lustre_lnet_parse_interfaces
659 * prase an interface string and populate descriptor structures
660 * intf_str - interface string of the format
661 * <intf>[<expr>], <intf>[<expr>],..
662 * nw_descr - network descriptor to populate
663 * init - True to initialize nw_descr
665 int lustre_lnet_parse_interfaces(char *intf_str,
666 struct lnet_dlc_network_descr *nw_descr);
669 * lustre_lnet_parse_nidstr
670 * This is a small wrapper around cfs_parse_nidlist.
671 * nidstr - A string parseable by cfs_parse_nidlist
672 * lnet_nidlist - An array of lnet_nid_t to hold the nids specified
674 * max_nids - Size of the lnet_nidlist array, and the maximum number of
675 * nids that can be expressed by the nidstring. If the
676 * nidstring expands to a larger number of nids than max_nids
677 * then an error is returned.
678 * err_str - char pointer where we store an informative error
679 * message when an error is encountered
681 * The number (> 0) of lnet_nid_t stored in the supplied array, or
682 * LUSTRE_CFG_RC_BAD_PARAM if:
684 * - nidstr contains an asterisk. This character is not allowed
685 * because it would cause the size of the expanded nidlist to exceed
686 * the maximum number of nids that is supported by expected callers
688 * - cfs_parse_nidlist fails to parse the nidstring
689 * - The nidlist populated by cfs_parse_nidlist is empty
690 * - The nidstring expands to a larger number of nids than max_nids
691 * - The nidstring expands to zero nids
692 * LUSTRE_CFG_RC_OUT_OF_MEM if:
693 * - cfs_expand_nidlist can return ENOMEM. We return out of mem in
696 int lustre_lnet_parse_nidstr(char *nidstr, lnet_nid_t *lnet_nidlist,
697 int max_nids, char *err_str);
700 * lustre_lnet_parse_nids
701 * Parse a set of nids into a locally allocated array and return the
702 * pointer of the array to the caller. The caller is responsible for
703 * freeing the array. If an initial array is provided then copy over
704 * the contents of that array into the new array and append to it the
706 * The nids can be of the form "nid [,nid, nid, nid]"
707 * nids: nids string to be parsed
708 * array: initial array of content
709 * size: num of elements in the array
710 * out_array: [OUT] new allocated array.
711 * Returns size of array
712 * sets the out_array to NULL on failure.
714 int lustre_lnet_parse_nids(char *nids, char **array, int size,
717 #endif /* LIB_LNET_CONFIG_API_H */