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
46 struct lnet_dlc_network_descr {
47 struct list_head network_on_rule;
49 struct list_head nw_intflist;
52 struct lnet_dlc_intf_descr {
53 struct list_head intf_on_network;
54 char intf_name[IFNAMSIZ];
55 struct cfs_expr_list *cpt_expr;
58 /* forward declaration of the cYAML structure. */
62 * lustre_lnet_config_lib_init()
63 * Initialize the Library to enable communication with the LNET kernel
64 * module. Returns the device ID or -EINVAL if there is an error
66 int lustre_lnet_config_lib_init();
69 * lustre_lnet_config_lib_uninit
70 * Uninitialize the DLC Library
72 void lustre_lnet_config_lib_uninit();
75 * lustre_lnet_config_ni_system
76 * Initialize/Uninitialize the lnet NI system.
78 * up - whehter to init or uninit the system
79 * load_ni_from_mod - load NI from mod params.
80 * seq_no - sequence number of the request
81 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
84 int lustre_lnet_config_ni_system(bool up, bool load_ni_from_mod,
85 int seq_no, struct cYAML **err_rc);
88 * lustre_lnet_config_route
89 * Send down an IOCTL to the kernel to configure the route
93 * hops - number of hops passed down by the user
94 * prio - priority of the route
95 * seq_no - sequence number of the request
96 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
98 int lustre_lnet_config_route(char *nw, char *gw, int hops, int prio,
99 int seq_no, struct cYAML **err_rc);
102 * lustre_lnet_del_route
103 * Send down an IOCTL to the kernel to delete a route
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_del_route(char *nw, char *gw, int seq_no,
111 struct cYAML **err_rc);
114 * lustre_lnet_show_route
115 * Send down an IOCTL to the kernel to show routes
116 * This function will get one route at a time and filter according to
117 * provided parameters. If no routes are available then it will dump all
118 * routes that are in the system.
120 * nw - network. Optional. Used to filter output
121 * gw - gateway. Optional. Used to filter ouptut
122 * hops - number of hops passed down by the user
123 * Optional. Used to filter output.
124 * prio - priority of the route. Optional. Used to filter output.
125 * detail - flag to indicate whether detail output is required
126 * seq_no - sequence number of the request
127 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
128 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
129 * backup - true to output only what's necessary for reconfiguring
132 int lustre_lnet_show_route(char *nw, char *gw,
133 int hops, int prio, int detail,
134 int seq_no, struct cYAML **show_rc,
135 struct cYAML **err_rc, bool backup);
138 * lustre_lnet_config_ni
139 * Send down an IOCTL to configure a network interface. It implicitly
140 * creates a network if one doesn't exist..
142 * nw_descr - network and interface descriptor
143 * global_cpts - globally defined CPTs
144 * ip2net - this parameter allows configuring multiple networks.
145 * it takes precedence over the net and intf parameters
146 * tunables - LND tunables
147 * seq_no - sequence number of the request
148 * lnd_tunables - lnet specific tunable parameters
149 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
151 int lustre_lnet_config_ni(struct lnet_dlc_network_descr *nw_descr,
152 struct cfs_expr_list *global_cpts,
154 struct lnet_ioctl_config_lnd_tunables *tunables,
155 int seq_no, struct cYAML **err_rc);
159 * Send down an IOCTL to delete a network interface. It implicitly
160 * deletes a network if it becomes empty of nis
162 * nw - network and interface list
163 * seq_no - sequence number of the request
164 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
166 int lustre_lnet_del_ni(struct lnet_dlc_network_descr *nw,
167 int seq_no, struct cYAML **err_rc);
170 * lustre_lnet_show_net
171 * Send down an IOCTL to show networks.
172 * This function will use the nw paramter to filter the output. If it's
173 * not provided then all networks are listed.
175 * nw - network to show. Optional. Used to filter output.
176 * detail - flag to indicate if we require detail output.
177 * seq_no - sequence number of the request
178 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
179 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
180 * backup - true to output only what's necessary for reconfiguring
183 int lustre_lnet_show_net(char *nw, int detail, int seq_no,
184 struct cYAML **show_rc, struct cYAML **err_rc,
188 * lustre_lnet_enable_routing
189 * Send down an IOCTL to enable or diable routing
191 * enable - 1 to enable routing, 0 to disable routing
192 * seq_no - sequence number of the request
193 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
195 int lustre_lnet_enable_routing(int enable, int seq_no,
196 struct cYAML **err_rc);
199 * lustre_lnet_config_numa_range
200 * Set the NUMA range which impacts the NIs to be selected
201 * during sending. If the NUMA range is large the NUMA
202 * distance between the message memory and the NI becomes
203 * less significant. The NUMA range is a relative number
204 * with no other meaning besides allowing a wider breadth
205 * for picking an NI to send from.
207 * range - numa range value.
208 * seq_no - sequence number of the request
209 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
212 int lustre_lnet_config_numa_range(int range, int seq_no,
213 struct cYAML **err_rc);
216 * lustre_lnet_show_num_range
217 * Get the currently set NUMA range
219 * seq_no - sequence number of the request
220 * show_rc - [OUT] struct cYAML tree containing NUMA range info
221 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
224 int lustre_lnet_show_numa_range(int seq_no, struct cYAML **show_rc,
225 struct cYAML **err_rc);
228 * lustre_lnet_config_ni_healthv
229 * set the health value of the NI. -1 resets the value to maximum.
231 * value: health value to set.
232 * all: true to set all local NIs to that value.
233 * ni_nid: NI NID to set its health value. all parameter always takes
235 * seq_no - sequence number of the request
236 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
239 int lustre_lnet_config_ni_healthv(int value, bool all, char *ni_nid,
240 int seq_no, struct cYAML **err_rc);
243 * lustre_lnet_config_peer_ni_healthv
244 * set the health value of the peer NI. -1 resets the value to maximum.
246 * value: health value to set.
247 * all: true to set all local NIs to that value.
248 * pni_nid: Peer NI NID to set its health value. all parameter always takes
250 * seq_no - sequence number of the request
251 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
254 int lustre_lnet_config_peer_ni_healthv(int value, bool all, char *pni_nid,
255 int seq_no, struct cYAML **err_rc);
258 * lustre_lnet_config_recov_intrv
259 * set the recovery interval in seconds. That's the interval to ping an
260 * unhealthy interface.
262 * intrv - recovery interval value to configure
263 * seq_no - sequence number of the request
264 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
267 int lustre_lnet_config_recov_intrv(int intrv, int seq_no, struct cYAML **err_rc);
270 * lustre_lnet_show_recov_intrv
271 * show the recovery interval set in the system
273 * seq_no - sequence number of the request
274 * show_rc - [OUT] struct cYAML tree containing health sensitivity info
275 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
278 int lustre_lnet_show_recov_intrv(int seq_no, struct cYAML **show_rc,
279 struct cYAML **err_rc);
282 * lustre_lnet_config_rtr_sensitivity
283 * sets the router sensitivity percentage. If the percentage health
284 * of a router interface drops below that it's considered failed
286 * sen - sensitivity value to configure
287 * seq_no - sequence number of the request
288 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
291 int lustre_lnet_config_rtr_sensitivity(int sen, int seq_no, struct cYAML **err_rc);
294 * lustre_lnet_config_hsensitivity
295 * sets the health sensitivity; the value by which to decrement the
296 * health value of a local or peer NI. If 0 then health is turned off
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_hsensitivity(int sen, int seq_no, struct cYAML **err_rc);
306 * lustre_lnet_show_hsensitivity
307 * show the health sensitivity in the system
309 * seq_no - sequence number of the request
310 * show_rc - [OUT] struct cYAML tree containing health sensitivity info
311 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
314 int lustre_lnet_show_hsensitivity(int seq_no, struct cYAML **show_rc,
315 struct cYAML **err_rc);
318 * lustre_lnet_show_rtr_sensitivity
319 * show the router sensitivity percentage 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_rtr_sensitivity(int seq_no, struct cYAML **show_rc,
327 struct cYAML **err_rc);
330 * lustre_lnet_config_transaction_to
331 * sets the timeout after which a message expires or a timeout event is
332 * propagated for an expired response.
334 * timeout - timeout value to configure
335 * seq_no - sequence number of the request
336 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
339 int lustre_lnet_config_transaction_to(int timeout, int seq_no, struct cYAML **err_rc);
342 * lustre_lnet_show_transaction_to
343 * show the transaction timeout in the system
345 * seq_no - sequence number of the request
346 * show_rc - [OUT] struct cYAML tree containing transaction timeout info
347 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
350 int lustre_lnet_show_transaction_to(int seq_no, struct cYAML **show_rc,
351 struct cYAML **err_rc);
354 * lustre_lnet_config_retry_count
355 * sets the maximum number of retries to resend a message
357 * count - maximum value to configure
358 * seq_no - sequence number of the request
359 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
362 int lustre_lnet_config_retry_count(int count, int seq_no, struct cYAML **err_rc);
365 * lustre_lnet_show_retry_count
366 * show current maximum number of retries in the system
368 * seq_no - sequence number of the request
369 * show_rc - [OUT] struct cYAML tree containing retry count info
370 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
373 int lustre_lnet_show_retry_count(int seq_no, struct cYAML **show_rc,
374 struct cYAML **err_rc);
376 int lustre_lnet_show_local_ni_recovq(int seq_no, struct cYAML **show_rc,
377 struct cYAML **err_rc);
379 int lustre_lnet_show_peer_ni_recovq(int seq_no, struct cYAML **show_rc,
380 struct cYAML **err_rc);
383 * lustre_lnet_config_max_intf
384 * Sets the maximum number of interfaces per node. this tunable is
385 * primarily useful for sanity checks prior to allocating memory.
387 * max - maximum value to configure
388 * seq_no - sequence number of the request
389 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
392 int lustre_lnet_config_max_intf(int max, int seq_no, struct cYAML **err_rc);
395 * lustre_lnet_show_max_intf
396 * show current maximum interface setting
398 * seq_no - sequence number of the request
399 * show_rc - [OUT] struct cYAML tree containing NUMA range info
400 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
403 int lustre_lnet_show_max_intf(int seq_no, struct cYAML **show_rc,
404 struct cYAML **err_rc);
407 * lustre_lnet_config_discovery
408 * Enable or disable peer discovery. Peer discovery is enabled by default.
410 * enable - non-0 enables, 0 disables
411 * seq_no - sequence number of the request
412 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
415 int lustre_lnet_config_discovery(int enable, int seq_no, struct cYAML **err_rc);
418 * lustre_lnet_show_discovery
419 * show current peer discovery setting
421 * seq_no - sequence number of the request
422 * show_rc - [OUT] struct cYAML tree containing NUMA range info
423 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
426 int lustre_lnet_show_discovery(int seq_no, struct cYAML **show_rc,
427 struct cYAML **err_rc);
430 * lustre_lnet_config_drop_asym_route
431 * Drop or accept asymmetrical route messages. Accept by default.
433 * drop - non-0 drops, 0 accepts
434 * seq_no - sequence number of the request
435 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
438 int lustre_lnet_config_drop_asym_route(int drop, int seq_no,
439 struct cYAML **err_rc);
442 * lustre_lnet_show_drop_asym_route
443 * show current drop asym route setting
445 * seq_no - sequence number of the request
446 * show_rc - [OUT] struct cYAML tree containing NUMA range info
447 * err_rc - [OUT] struct cYAML tree describing the error. Freed by
450 int lustre_lnet_show_drop_asym_route(int seq_no, struct cYAML **show_rc,
451 struct cYAML **err_rc);
454 * lustre_lnet_config_buffers
455 * Send down an IOCTL to configure routing buffer sizes. A value of 0 means
456 * default that particular buffer to default size. A value of -1 means
457 * leave the value of the buffer un changed.
459 * tiny - tiny buffers
460 * small - small buffers
461 * large - large buffers.
462 * seq_no - sequence number of the request
463 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
465 int lustre_lnet_config_buffers(int tiny, int small, int large,
466 int seq_no, struct cYAML **err_rc);
469 * lustre_lnet_show_routing
470 * Send down an IOCTL to dump buffers and routing status
471 * This function is used to dump buffers for all CPU partitions.
473 * seq_no - sequence number of the request
474 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
475 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
476 * backup - true to output only what's necessary for reconfiguring
479 int lustre_lnet_show_routing(int seq_no, struct cYAML **show_rc,
480 struct cYAML **err_rc, bool backup);
483 * lustre_lnet_show_stats
484 * Shows internal LNET statistics. This is useful to display the
485 * current LNET activity, such as number of messages route, etc
487 * seq_no - sequence number of the command
488 * show_rc - YAML structure of the resultant show
489 * err_rc - YAML strucutre of the resultant return code.
491 int lustre_lnet_show_stats(int seq_no, struct cYAML **show_rc,
492 struct cYAML **err_rc);
495 * lustre_lnet_config_peer_nid
496 * Add a peer nid to a peer with primary nid pnid. If no pnid is given
497 * then the first nid in the nid list becomes the primary nid for
498 * a newly created peer.
499 * Otherwise if pnid is provided and it's unique then a new peer is
500 * created with pnid as the primary NID and the nids in the nid list as
502 * If any of the peers nids provided in with exception to the pnid is
503 * not unique the operation fails. Some peer nids might have already
504 * been added. It's the role of the caller of this API to remove the
505 * added NIDs if they wish.
507 * pnid - Primary NID of the peer
508 * nid - list of nids to add
509 * num_nids - number of nids in the nid array
510 * mr - true if this peer is MR capable.
511 * ip2nets - true if a list of nid expressions are given to configure
513 * seq_no - sequence number of the command
514 * err_rc - YAML strucutre of the resultant return code.
516 int lustre_lnet_config_peer_nid(char *pnid, char **nid, int num_nids,
517 bool mr, bool ip2nets, int seq_no,
518 struct cYAML **err_rc);
521 * lustre_lnet_del_peer_nid
522 * Delete the nids given in the nid list from the peer with primary NID
523 * pnid. If pnid is NULL or it doesn't identify a peer the operation
524 * fails and no change happens to the system.
525 * The operation is aborted on the first NID that fails to be deleted.
527 * pnid - Primary NID of the peer
528 * nid - list of nids to add
529 * num_nids - number of nids in the nid array
530 * ip2nets - used to specify a range of nids
531 * seq_no - sequence number of the command
532 * err_rc - YAML strucutre of the resultant return code.
534 int lustre_lnet_del_peer_nid(char *pnid, char **nid, int num_nids,
535 bool ip2nets, int seq_no, struct cYAML **err_rc);
538 * lustre_lnet_show_peer
539 * Show the peer identified by nid, knid. If knid is NULL all
540 * peers in the system are shown.
542 * knid - A NID of the peer
543 * detail - display detailed information
544 * seq_no - sequence number of the command
545 * show_rc - YAML structure of the resultant show
546 * err_rc - YAML strucutre of the resultant return code.
547 * backup - true to output only what's necessary for reconfiguring
551 int lustre_lnet_show_peer(char *knid, int detail, int seq_no,
552 struct cYAML **show_rc, struct cYAML **err_rc,
556 * lustre_lnet_list_peer
557 * List the known peers.
559 * seq_no - sequence number of the command
560 * show_rc - YAML structure of the resultant show
561 * err_rc - YAML strucutre of the resultant return code.
564 int lustre_lnet_list_peer(int seq_no,
565 struct cYAML **show_rc, struct cYAML **err_rc);
567 /* lustre_lnet_ping_nid
568 * Ping the nid list, pnids.
570 * pnids - NID list to ping.
571 * timeout - timeout(seconds) for ping.
572 * seq_no - sequence number of the command.
573 * show_rc - YAML structure of the resultant show.
574 * err_rc - YAML strucutre of the resultant return code.
577 int lustre_lnet_ping_nid(char *pnid, int timeout, int seq_no,
578 struct cYAML **show_rc, struct cYAML **err_rc);
580 /* lustre_lnet_discover_nid
581 * Discover the nid list, pnids.
583 * pnids - NID list to discover.
584 * force - force discovery.
585 * seq_no - sequence number of the command.
586 * show_rc - YAML structure of the resultant show.
587 * err_rc - YAML strucutre of the resultant return code.
590 int lustre_lnet_discover_nid(char *pnid, int force, int seq_no,
591 struct cYAML **show_rc, struct cYAML **err_rc);
595 * Parses the provided YAML file and then calls the specific APIs
596 * to configure the entities identified in the file
599 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
601 int lustre_yaml_config(char *f, struct cYAML **err_rc);
605 * Parses the provided YAML file and then calls the specific APIs
606 * to delete the entities identified in the file
609 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
611 int lustre_yaml_del(char *f, struct cYAML **err_rc);
615 * Parses the provided YAML file and then calls the specific APIs
616 * to show the entities identified in the file
619 * show_rc - [OUT] The show output in YAML. Must be freed by caller.
620 * err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
622 int lustre_yaml_show(char *f, struct cYAML **show_rc,
623 struct cYAML **err_rc);
627 * Parses the provided YAML file and then calls the specific APIs
628 * to execute 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_exec(char *f, struct cYAML **show_rc,
635 struct cYAML **err_rc);
638 * lustre_lnet_init_nw_descr
639 * initialize the network descriptor structure for use
641 void lustre_lnet_init_nw_descr(struct lnet_dlc_network_descr *nw_descr);
644 * lustre_lnet_parse_interfaces
645 * prase an interface string and populate descriptor structures
646 * intf_str - interface string of the format
647 * <intf>[<expr>], <intf>[<expr>],..
648 * nw_descr - network descriptor to populate
649 * init - True to initialize nw_descr
651 int lustre_lnet_parse_interfaces(char *intf_str,
652 struct lnet_dlc_network_descr *nw_descr);
655 * lustre_lnet_parse_nids
656 * Parse a set of nids into a locally allocated array and return the
657 * pointer of the array to the caller. The caller is responsible for
658 * freeing the array. If an initial array is provided then copy over
659 * the contents of that array into the new array and append to it the
661 * The nids can be of the form "nid [,nid, nid, nid]"
662 * nids: nids string to be parsed
663 * array: initial array of content
664 * size: num of elements in the array
665 * out_array: [OUT] new allocated array.
666 * Returns size of array
667 * sets the out_array to NULL on failure.
669 int lustre_lnet_parse_nids(char *nids, char **array, int size,
672 #endif /* LIB_LNET_CONFIG_API_H */