lnet/utils/lnetconfig/liblnetconfig.h

   1 /*
   2  * LGPL HEADER START
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   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.
  10  *
  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.
  15  *
  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/>.
  18  *
  19  * LGPL HEADER END
  20  *
  21  * Copyright (c) 2014, 2017, Intel Corporation.
  22  *
  23  * Author:
  24  *   Amir Shehata <amir.shehata@intel.com>
  25  */
  26
  27 #ifndef LIB_LNET_CONFIG_API_H
  28 #define LIB_LNET_CONFIG_API_H
  29
  30 #include <libcfs/util/string.h>
  31 #include <linux/lnet/lnet-dlc.h>
  32 #include <linux/lnet/nidstr.h>
  33
  34 #define LUSTRE_CFG_RC_NO_ERR                     0
  35 #define LUSTRE_CFG_RC_BAD_PARAM                 -1
  36 #define LUSTRE_CFG_RC_MISSING_PARAM             -2
  37 #define LUSTRE_CFG_RC_OUT_OF_RANGE_PARAM        -3
  38 #define LUSTRE_CFG_RC_OUT_OF_MEM                -4
  39 #define LUSTRE_CFG_RC_GENERIC_ERR               -5
  40 #define LUSTRE_CFG_RC_NO_MATCH                  -6
  41 #define LUSTRE_CFG_RC_MATCH                     -7
  42
  43 struct lnet_dlc_network_descr {
  44         struct list_head network_on_rule;
  45         __u32 nw_id;
  46         struct list_head nw_intflist;
  47 };
  48
  49 struct lnet_dlc_intf_descr {
  50         struct list_head intf_on_network;
  51         char intf_name[LNET_MAX_STR_LEN];
  52         struct cfs_expr_list *cpt_expr;
  53 };
  54
  55 /* forward declaration of the cYAML structure. */
  56 struct cYAML;
  57
  58 /*
  59  * lustre_lnet_config_lib_init()
  60  *   Initialize the Library to enable communication with the LNET kernel
  61  *   module.  Returns the device ID or -EINVAL if there is an error
  62  */
  63 int lustre_lnet_config_lib_init();
  64
  65 /*
  66  * lustre_lnet_config_lib_uninit
  67  *      Uninitialize the DLC Library
  68  */
  69 void lustre_lnet_config_lib_uninit();
  70
  71 /*
  72  * lustre_lnet_config_ni_system
  73  *   Initialize/Uninitialize the lnet NI system.
  74  *
  75  *   up - whehter to init or uninit the system
  76  *   load_ni_from_mod - load NI from mod params.
  77  *   seq_no - sequence number of the request
  78  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
  79  *            caller
  80  */
  81 int lustre_lnet_config_ni_system(bool up, bool load_ni_from_mod,
  82                                  int seq_no, struct cYAML **err_rc);
  83
  84 /*
  85  * lustre_lnet_config_route
  86  *   Send down an IOCTL to the kernel to configure the route
  87  *
  88  *   nw - network
  89  *   gw - gateway
  90  *   hops - number of hops passed down by the user
  91  *   prio - priority of the route
  92  *   seq_no - sequence number of the request
  93  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
  94  */
  95 int lustre_lnet_config_route(char *nw, char *gw, int hops, int prio,
  96                              int seq_no, struct cYAML **err_rc);
  97
  98 /*
  99  * lustre_lnet_del_route
 100  *   Send down an IOCTL to the kernel to delete a route
 101  *
 102  *   nw - network
 103  *   gw - gateway
 104  *   seq_no - sequence number of the request
 105  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 106  */
 107 int lustre_lnet_del_route(char *nw, char *gw, int seq_no,
 108                           struct cYAML **err_rc);
 109
 110 /*
 111  * lustre_lnet_show_route
 112  *   Send down an IOCTL to the kernel to show routes
 113  *   This function will get one route at a time and filter according to
 114  *   provided parameters. If no routes are available then it will dump all
 115  *   routes that are in the system.
 116  *
 117  *   nw - network.  Optional.  Used to filter output
 118  *   gw - gateway. Optional. Used to filter ouptut
 119  *   hops - number of hops passed down by the user
 120  *          Optional.  Used to filter output.
 121  *   prio - priority of the route.  Optional.  Used to filter output.
 122  *   detail - flag to indicate whether detail output is required
 123  *   seq_no - sequence number of the request
 124  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 125  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 126  *   backup - true to output only what's necessary for reconfiguring
 127  *            a node.
 128  */
 129 int lustre_lnet_show_route(char *nw, char *gw,
 130                            int hops, int prio, int detail,
 131                            int seq_no, struct cYAML **show_rc,
 132                            struct cYAML **err_rc, bool backup);
 133
 134 /*
 135  * lustre_lnet_config_ni
 136  *   Send down an IOCTL to configure a network interface. It implicitly
 137  *   creates a network if one doesn't exist..
 138  *
 139  *   nw_descr - network and interface descriptor
 140  *   global_cpts - globally defined CPTs
 141  *   ip2net - this parameter allows configuring multiple networks.
 142  *      it takes precedence over the net and intf parameters
 143  *   tunables - LND tunables
 144  *   seq_no - sequence number of the request
 145  *   lnd_tunables - lnet specific tunable parameters
 146  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 147  */
 148 int lustre_lnet_config_ni(struct lnet_dlc_network_descr *nw_descr,
 149                           struct cfs_expr_list *global_cpts,
 150                           char *ip2net,
 151                           struct lnet_ioctl_config_lnd_tunables *tunables,
 152                           int seq_no, struct cYAML **err_rc);
 153
 154 /*
 155  * lustre_lnet_del_ni
 156  *   Send down an IOCTL to delete a network interface. It implicitly
 157  *   deletes a network if it becomes empty of nis
 158  *
 159  *   nw  - network and interface list
 160  *   seq_no - sequence number of the request
 161  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 162  */
 163 int lustre_lnet_del_ni(struct lnet_dlc_network_descr *nw,
 164                        int seq_no, struct cYAML **err_rc);
 165
 166 /*
 167  * lustre_lnet_show_net
 168  *   Send down an IOCTL to show networks.
 169  *   This function will use the nw paramter to filter the output.  If it's
 170  *   not provided then all networks are listed.
 171  *
 172  *   nw - network to show.  Optional.  Used to filter output.
 173  *   detail - flag to indicate if we require detail output.
 174  *   seq_no - sequence number of the request
 175  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 176  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 177  *   backup - true to output only what's necessary for reconfiguring
 178  *            a node.
 179  */
 180 int lustre_lnet_show_net(char *nw, int detail, int seq_no,
 181                          struct cYAML **show_rc, struct cYAML **err_rc,
 182                          bool backup);
 183
 184 /*
 185  * lustre_lnet_enable_routing
 186  *   Send down an IOCTL to enable or diable routing
 187  *
 188  *   enable - 1 to enable routing, 0 to disable routing
 189  *   seq_no - sequence number of the request
 190  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 191  */
 192 int lustre_lnet_enable_routing(int enable, int seq_no,
 193                                struct cYAML **err_rc);
 194
 195 /*
 196  * lustre_lnet_config_numa_range
 197  *   Set the NUMA range which impacts the NIs to be selected
 198  *   during sending. If the NUMA range is large the NUMA
 199  *   distance between the message memory and the NI becomes
 200  *   less significant. The NUMA range is a relative number
 201  *   with no other meaning besides allowing a wider breadth
 202  *   for picking an NI to send from.
 203  *
 204  *   range - numa range value.
 205  *   seq_no - sequence number of the request
 206  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 207  *   caller
 208  */
 209 int lustre_lnet_config_numa_range(int range, int seq_no,
 210                                   struct cYAML **err_rc);
 211
 212 /*
 213  * lustre_lnet_show_num_range
 214  *   Get the currently set NUMA range
 215  *
 216  *   seq_no - sequence number of the request
 217  *   show_rc - [OUT] struct cYAML tree containing NUMA range info
 218  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 219  *   caller
 220  */
 221 int lustre_lnet_show_numa_range(int seq_no, struct cYAML **show_rc,
 222                                 struct cYAML **err_rc);
 223
 224 /*
 225  * lustre_lnet_config_max_intf
 226  *   Sets the maximum number of interfaces per node. this tunable is
 227  *   primarily useful for sanity checks prior to allocating memory.
 228  *
 229  *   max - maximum value to configure
 230  *   seq_no - sequence number of the request
 231  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 232  *   caller
 233  */
 234 int lustre_lnet_config_max_intf(int max, int seq_no, struct cYAML **err_rc);
 235
 236 /*
 237  * lustre_lnet_show_max_intf
 238  *    show current maximum interface setting
 239  *
 240  *   seq_no - sequence number of the request
 241  *   show_rc - [OUT] struct cYAML tree containing NUMA range info
 242  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 243  *   caller
 244  */
 245 int lustre_lnet_show_max_intf(int seq_no, struct cYAML **show_rc,
 246                               struct cYAML **err_rc);
 247
 248 /*
 249  * lustre_lnet_config_discovery
 250  *   Enable or disable peer discovery. Peer discovery is enabled by default.
 251  *
 252  *   enable - non-0 enables, 0 disables
 253  *   seq_no - sequence number of the request
 254  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 255  *   caller
 256  */
 257 int lustre_lnet_config_discovery(int enable, int seq_no, struct cYAML **err_rc);
 258
 259 /*
 260  * lustre_lnet_show_discovery
 261  *    show current peer discovery setting
 262  *
 263  *   seq_no - sequence number of the request
 264  *   show_rc - [OUT] struct cYAML tree containing NUMA range info
 265  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 266  *   caller
 267  */
 268 int lustre_lnet_show_discovery(int seq_no, struct cYAML **show_rc,
 269                                struct cYAML **err_rc);
 270
 271 /*
 272  * lustre_lnet_config_buffers
 273  *   Send down an IOCTL to configure routing buffer sizes.  A value of 0 means
 274  *   default that particular buffer to default size. A value of -1 means
 275  *   leave the value of the buffer un changed.
 276  *
 277  *   tiny - tiny buffers
 278  *   small - small buffers
 279  *   large - large buffers.
 280  *   seq_no - sequence number of the request
 281  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 282  */
 283 int lustre_lnet_config_buffers(int tiny, int small, int large,
 284                                int seq_no, struct cYAML **err_rc);
 285
 286 /*
 287  * lustre_lnet_show_routing
 288  *   Send down an IOCTL to dump buffers and routing status
 289  *   This function is used to dump buffers for all CPU partitions.
 290  *
 291  *   seq_no - sequence number of the request
 292  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 293  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 294  *   backup - true to output only what's necessary for reconfiguring
 295  *            a node.
 296  */
 297 int lustre_lnet_show_routing(int seq_no, struct cYAML **show_rc,
 298                              struct cYAML **err_rc, bool backup);
 299
 300 /*
 301  * lustre_lnet_show_stats
 302  *   Shows internal LNET statistics.  This is useful to display the
 303  *   current LNET activity, such as number of messages route, etc
 304  *
 305  *     seq_no - sequence number of the command
 306  *     show_rc - YAML structure of the resultant show
 307  *     err_rc - YAML strucutre of the resultant return code.
 308  */
 309 int lustre_lnet_show_stats(int seq_no, struct cYAML **show_rc,
 310                            struct cYAML **err_rc);
 311
 312 /*
 313  * lustre_lnet_config_peer_nid
 314  *   Add a peer nid to a peer with primary nid pnid. If no pnid is given
 315  *   then the first nid in the nid list becomes the primary nid for
 316  *   a newly created peer.
 317  *   Otherwise if pnid is provided and it's unique then a new peer is
 318  *   created with pnid as the primary NID and the nids in the nid list as
 319  *   secondary nids.
 320  *   If any of the peers nids provided in with exception to the pnid is
 321  *   not unique the operation fails. Some peer nids might have already
 322  *   been added. It's the role of the caller of this API to remove the
 323  *   added NIDs if they wish.
 324  *
 325  *     pnid - Primary NID of the peer
 326  *     nid - list of nids to add
 327  *     num_nids - number of nids in the nid array
 328  *     mr - true if this peer is MR capable.
 329  *     seq_no - sequence number of the command
 330  *     err_rc - YAML strucutre of the resultant return code.
 331  */
 332 int lustre_lnet_config_peer_nid(char *pnid, char **nid, int num_nids,
 333                                 bool mr, int seq_no, struct cYAML **err_rc);
 334
 335 /*
 336  * lustre_lnet_del_peer_nid
 337  *  Delete the nids given in the nid list from the peer with primary NID
 338  *  pnid. If pnid is NULL or it doesn't identify a peer the operation
 339  *  fails and no change happens to the system.
 340  *  The operation is aborted on the first NID that fails to be deleted.
 341  *
 342  *     pnid - Primary NID of the peer
 343  *     nid - list of nids to add
 344  *     num_nids - number of nids in the nid array
 345  *     seq_no - sequence number of the command
 346  *     err_rc - YAML strucutre of the resultant return code.
 347  */
 348 int lustre_lnet_del_peer_nid(char *pnid, char **nid, int num_nids,
 349                              int seq_no, struct cYAML **err_rc);
 350
 351 /*
 352  * lustre_lnet_show_peer
 353  *   Show the peer identified by nid, knid. If knid is NULL all
 354  *   peers in the system are shown.
 355  *
 356  *     knid - A NID of the peer
 357  *     detail - display detailed information
 358  *     seq_no - sequence number of the command
 359  *     show_rc - YAML structure of the resultant show
 360  *     err_rc - YAML strucutre of the resultant return code.
 361  *     backup - true to output only what's necessary for reconfiguring
 362  *              a node.
 363  *
 364  */
 365 int lustre_lnet_show_peer(char *knid, int detail, int seq_no,
 366                           struct cYAML **show_rc, struct cYAML **err_rc,
 367                           bool backup);
 368
 369 /*
 370  * lustre_lnet_list_peer
 371  *   List the known peers.
 372  *
 373  *     seq_no - sequence number of the command
 374  *     show_rc - YAML structure of the resultant show
 375  *     err_rc - YAML strucutre of the resultant return code.
 376  *
 377  */
 378 int lustre_lnet_list_peer(int seq_no,
 379                           struct cYAML **show_rc, struct cYAML **err_rc);
 380
 381 /* lustre_lnet_ping_nid
 382  *   Ping the nid list, pnids.
 383  *
 384  *    pnids - NID list to ping.
 385  *    timeout - timeout(seconds) for ping.
 386  *    seq_no - sequence number of the command.
 387  *    show_rc - YAML structure of the resultant show.
 388  *    err_rc - YAML strucutre of the resultant return code.
 389  *
 390  */
 391 int lustre_lnet_ping_nid(char *pnid, int timeout, int seq_no,
 392                         struct cYAML **show_rc, struct cYAML **err_rc);
 393
 394 /* lustre_lnet_discover_nid
 395  *   Discover the nid list, pnids.
 396  *
 397  *    pnids - NID list to discover.
 398  *    force - force discovery.
 399  *    seq_no - sequence number of the command.
 400  *    show_rc - YAML structure of the resultant show.
 401  *    err_rc - YAML strucutre of the resultant return code.
 402  *
 403  */
 404 int lustre_lnet_discover_nid(char *pnid, int force, int seq_no,
 405                              struct cYAML **show_rc, struct cYAML **err_rc);
 406
 407 /*
 408  * lustre_yaml_config
 409  *   Parses the provided YAML file and then calls the specific APIs
 410  *   to configure the entities identified in the file
 411  *
 412  *   f - YAML file
 413  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 414  */
 415 int lustre_yaml_config(char *f, struct cYAML **err_rc);
 416
 417 /*
 418  * lustre_yaml_del
 419  *   Parses the provided YAML file and then calls the specific APIs
 420  *   to delete the entities identified in the file
 421  *
 422  *   f - YAML file
 423  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 424  */
 425 int lustre_yaml_del(char *f, struct cYAML **err_rc);
 426
 427 /*
 428  * lustre_yaml_show
 429  *   Parses the provided YAML file and then calls the specific APIs
 430  *   to show the entities identified in the file
 431  *
 432  *   f - YAML file
 433  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 434  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 435  */
 436 int lustre_yaml_show(char *f, struct cYAML **show_rc,
 437                      struct cYAML **err_rc);
 438
 439 /*
 440  * lustre_yaml_exec
 441  *   Parses the provided YAML file and then calls the specific APIs
 442  *   to execute the entities identified in the file
 443  *
 444  *   f - YAML file
 445  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 446  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 447  */
 448 int lustre_yaml_exec(char *f, struct cYAML **show_rc,
 449                      struct cYAML **err_rc);
 450
 451 /*
 452  * lustre_lnet_init_nw_descr
 453  *      initialize the network descriptor structure for use
 454  */
 455 void lustre_lnet_init_nw_descr(struct lnet_dlc_network_descr *nw_descr);
 456
 457 /*
 458  * lustre_lnet_parse_interfaces
 459  *      prase an interface string and populate descriptor structures
 460  *              intf_str - interface string of the format
 461  *                      <intf>[<expr>], <intf>[<expr>],..
 462  *              nw_descr - network descriptor to populate
 463  *              init - True to initialize nw_descr
 464  */
 465 int lustre_lnet_parse_interfaces(char *intf_str,
 466                                  struct lnet_dlc_network_descr *nw_descr);
 467
 468 /*
 469  * lustre_lnet_parse_nids
 470  *      Parse a set of nids into a locally allocated array and return the
 471  *      pointer of the array to the caller. The caller is responsible for
 472  *      freeing the array. If an initial array is provided then copy over
 473  *      the contents of that array into the new array and append to it the
 474  *      new content.
 475  *      The nids can be of the form "nid [,nid, nid, nid]"
 476  *              nids: nids string to be parsed
 477  *              array: initial array of content
 478  *              size: num of elements in the array
 479  *              out_array: [OUT] new allocated array.
 480  *      Returns size of array
 481  *              sets the out_array to NULL on failure.
 482  */
 483 int lustre_lnet_parse_nids(char *nids, char **array, int size,
 484                            char ***out_array);
 485
 486 #endif /* LIB_LNET_CONFIG_API_H */