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, 2016, 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 <lnet/lnet.h>
  31
  32 #define LUSTRE_CFG_RC_NO_ERR                     0
  33 #define LUSTRE_CFG_RC_BAD_PARAM                 -1
  34 #define LUSTRE_CFG_RC_MISSING_PARAM             -2
  35 #define LUSTRE_CFG_RC_OUT_OF_RANGE_PARAM        -3
  36 #define LUSTRE_CFG_RC_OUT_OF_MEM                -4
  37 #define LUSTRE_CFG_RC_GENERIC_ERR               -5
  38 #define LUSTRE_CFG_RC_NO_MATCH                  -6
  39 #define LUSTRE_CFG_RC_MATCH                     -7
  40 #define LUSTRE_CFG_RC_SKIP                      -8
  41 #define LUSTRE_CFG_RC_LAST_ELEM                 -9
  42
  43 #include <lnet/lnet.h>
  44 #include <libcfs/util/string.h>
  45
  46 struct lnet_dlc_network_descr {
  47         struct list_head network_on_rule;
  48         __u32 nw_id;
  49         struct list_head nw_intflist;
  50 };
  51
  52 struct lnet_dlc_intf_descr {
  53         struct list_head intf_on_network;
  54         char intf_name[LNET_MAX_STR_LEN];
  55         struct cfs_expr_list *cpt_expr;
  56 };
  57
  58 /* forward declaration of the cYAML structure. */
  59 struct cYAML;
  60
  61 /*
  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
  65  */
  66 int lustre_lnet_config_lib_init();
  67
  68 /*
  69  * lustre_lnet_config_lib_uninit
  70  *      Uninitialize the DLC Library
  71  */
  72 void lustre_lnet_config_lib_uninit();
  73
  74 /*
  75  * lustre_lnet_config_ni_system
  76  *   Initialize/Uninitialize the lnet NI system.
  77  *
  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
  82  *            caller
  83  */
  84 int lustre_lnet_config_ni_system(bool up, bool load_ni_from_mod,
  85                                  int seq_no, struct cYAML **err_rc);
  86
  87 /*
  88  * lustre_lnet_config_route
  89  *   Send down an IOCTL to the kernel to configure the route
  90  *
  91  *   nw - network
  92  *   gw - gateway
  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
  97  */
  98 int lustre_lnet_config_route(char *nw, char *gw, int hops, int prio,
  99                              int seq_no, struct cYAML **err_rc);
 100
 101 /*
 102  * lustre_lnet_del_route
 103  *   Send down an IOCTL to the kernel to delete a route
 104  *
 105  *   nw - network
 106  *   gw - gateway
 107  *   seq_no - sequence number of the request
 108  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 109  */
 110 int lustre_lnet_del_route(char *nw, char *gw, int seq_no,
 111                           struct cYAML **err_rc);
 112
 113 /*
 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.
 119  *
 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  */
 130 int lustre_lnet_show_route(char *nw, char *gw,
 131                            int hops, int prio, int detail,
 132                            int seq_no, struct cYAML **show_rc,
 133                            struct cYAML **err_rc);
 134
 135 /*
 136  * lustre_lnet_config_ni
 137  *   Send down an IOCTL to configure a network interface. It implicitly
 138  *   creates a network if one doesn't exist..
 139  *
 140  *   nw_descr - network and interface descriptor
 141  *   global_cpts - globally defined CPTs
 142  *   ip2net - this parameter allows configuring multiple networks.
 143  *      it takes precedence over the net and intf parameters
 144  *   tunables - LND tunables
 145  *   seq_no - sequence number of the request
 146  *   lnd_tunables - lnet specific tunable parameters
 147  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 148  */
 149 int lustre_lnet_config_ni(struct lnet_dlc_network_descr *nw_descr,
 150                           struct cfs_expr_list *global_cpts,
 151                           char *ip2net,
 152                           struct lnet_ioctl_config_lnd_tunables *tunables,
 153                           int seq_no, struct cYAML **err_rc);
 154
 155 /*
 156  * lustre_lnet_del_ni
 157  *   Send down an IOCTL to delete a network interface. It implicitly
 158  *   deletes a network if it becomes empty of nis
 159  *
 160  *   nw  - network and interface list
 161  *   seq_no - sequence number of the request
 162  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 163  */
 164 int lustre_lnet_del_ni(struct lnet_dlc_network_descr *nw,
 165                        int seq_no, struct cYAML **err_rc);
 166
 167 /*
 168  * lustre_lnet_show_net
 169  *   Send down an IOCTL to show networks.
 170  *   This function will use the nw paramter to filter the output.  If it's
 171  *   not provided then all networks are listed.
 172  *
 173  *   nw - network to show.  Optional.  Used to filter output.
 174  *   detail - flag to indicate if we require detail output.
 175  *   seq_no - sequence number of the request
 176  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 177  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 178  */
 179 int lustre_lnet_show_net(char *nw, int detail, int seq_no,
 180                          struct cYAML **show_rc, struct cYAML **err_rc);
 181
 182 /*
 183  * lustre_lnet_enable_routing
 184  *   Send down an IOCTL to enable or diable routing
 185  *
 186  *   enable - 1 to enable routing, 0 to disable routing
 187  *   seq_no - sequence number of the request
 188  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 189  */
 190 int lustre_lnet_enable_routing(int enable, int seq_no,
 191                                struct cYAML **err_rc);
 192
 193 /*
 194  * lustre_lnet_config_numa_range
 195  *   Set the NUMA range which impacts the NIs to be selected
 196  *   during sending. If the NUMA range is large the NUMA
 197  *   distance between the message memory and the NI becomes
 198  *   less significant. The NUMA range is a relative number
 199  *   with no other meaning besides allowing a wider breadth
 200  *   for picking an NI to send from.
 201  *
 202  *   range - numa range value.
 203  *   seq_no - sequence number of the request
 204  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 205  *   caller
 206  */
 207 int lustre_lnet_config_numa_range(int range, int seq_no,
 208                                   struct cYAML **err_rc);
 209
 210 /*
 211  * lustre_lnet_show_num_range
 212  *   Get the currently set NUMA range
 213  *
 214  *   seq_no - sequence number of the request
 215  *   show_rc - [OUT] struct cYAML tree containing NUMA range info
 216  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 217  *   caller
 218  */
 219 int lustre_lnet_show_numa_range(int seq_no, struct cYAML **show_rc,
 220                                 struct cYAML **err_rc);
 221
 222 /*
 223  * lustre_lnet_config_buffers
 224  *   Send down an IOCTL to configure routing buffer sizes.  A value of 0 means
 225  *   default that particular buffer to default size. A value of -1 means
 226  *   leave the value of the buffer un changed.
 227  *
 228  *   tiny - tiny buffers
 229  *   small - small buffers
 230  *   large - large buffers.
 231  *   seq_no - sequence number of the request
 232  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 233  */
 234 int lustre_lnet_config_buffers(int tiny, int small, int large,
 235                                int seq_no, struct cYAML **err_rc);
 236
 237 /*
 238  * lustre_lnet_show_routing
 239  *   Send down an IOCTL to dump buffers and routing status
 240  *   This function is used to dump buffers for all CPU partitions.
 241  *
 242  *   seq_no - sequence number of the request
 243  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 244  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 245  */
 246 int lustre_lnet_show_routing(int seq_no, struct cYAML **show_rc,
 247                              struct cYAML **err_rc);
 248
 249 /*
 250  * lustre_lnet_show_stats
 251  *   Shows internal LNET statistics.  This is useful to display the
 252  *   current LNET activity, such as number of messages route, etc
 253  *
 254  *     seq_no - sequence number of the command
 255  *     show_rc - YAML structure of the resultant show
 256  *     err_rc - YAML strucutre of the resultant return code.
 257  */
 258 int lustre_lnet_show_stats(int seq_no, struct cYAML **show_rc,
 259                            struct cYAML **err_rc);
 260
 261 /*
 262  * lustre_lnet_config_peer_nid
 263  *   Add a peer nid to a peer with primary nid pnid. If no pnid is given
 264  *   then the first nid in the nid list becomes the primary nid for
 265  *   a newly created peer.
 266  *   Otherwise if pnid is provided and it's unique then a new peer is
 267  *   created with pnid as the primary NID and the nids in the nid list as
 268  *   secondary nids.
 269  *   If any of the peers nids provided in with exception to the pnid is
 270  *   not unique the operation fails. Some peer nids might have already
 271  *   been added. It's the role of the caller of this API to remove the
 272  *   added NIDs if they wish.
 273  *
 274  *     pnid - Primary NID of the peer
 275  *     nid - list of nids to add
 276  *     num_nids - number of nids in the nid array
 277  *     mr - true if this peer is MR capable.
 278  *     ip2nets - true if a list of nid expressions are given to configure
 279  *     multiple peers
 280  *     seq_no - sequence number of the command
 281  *     err_rc - YAML strucutre of the resultant return code.
 282  */
 283 int lustre_lnet_config_peer_nid(char *pnid, char **nid, int num_nids,
 284                                 bool mr, bool ip2nets, int seq_no,
 285                                 struct cYAML **err_rc);
 286
 287 /*
 288  * lustre_lnet_del_peer_nid
 289  *  Delete the nids given in the nid list from the peer with primary NID
 290  *  pnid. If pnid is NULL or it doesn't identify a peer the operation
 291  *  fails and no change happens to the system.
 292  *  The operation is aborted on the first NID that fails to be deleted.
 293  *
 294  *     pnid - Primary NID of the peer
 295  *     nid - list of nids to add
 296  *     num_nids - number of nids in the nid array
 297  *     ip2nets - used to specify a range of nids
 298  *     seq_no - sequence number of the command
 299  *     err_rc - YAML strucutre of the resultant return code.
 300  */
 301 int lustre_lnet_del_peer_nid(char *pnid, char **nid, int num_nids,
 302                              bool ip2nets, int seq_no, struct cYAML **err_rc);
 303
 304 /*
 305  * lustre_lnet_show_peer
 306  *   Show the peer identified by nid, knid. If knid is NULL all
 307  *   peers in the system are shown.
 308  *
 309  *     knid - A NID of the peer
 310  *     detail - display detailed information
 311  *     seq_no - sequence number of the command
 312  *     show_rc - YAML structure of the resultant show
 313  *     err_rc - YAML strucutre of the resultant return code.
 314  *
 315  */
 316 int lustre_lnet_show_peer(char *knid, int detail, int seq_no,
 317                           struct cYAML **show_rc, struct cYAML **err_rc);
 318
 319 /*
 320  * lustre_yaml_config
 321  *   Parses the provided YAML file and then calls the specific APIs
 322  *   to configure the entities identified in the file
 323  *
 324  *   f - YAML file
 325  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 326  */
 327 int lustre_yaml_config(char *f, struct cYAML **err_rc);
 328
 329 /*
 330  * lustre_yaml_del
 331  *   Parses the provided YAML file and then calls the specific APIs
 332  *   to delete the entities identified in the file
 333  *
 334  *   f - YAML file
 335  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 336  */
 337 int lustre_yaml_del(char *f, struct cYAML **err_rc);
 338
 339 /*
 340  * lustre_yaml_show
 341  *   Parses the provided YAML file and then calls the specific APIs
 342  *   to show the entities identified in the file
 343  *
 344  *   f - YAML file
 345  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 346  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 347  */
 348 int lustre_yaml_show(char *f, struct cYAML **show_rc,
 349                      struct cYAML **err_rc);
 350
 351 /*
 352  * lustre_lnet_init_nw_descr
 353  *      initialize the network descriptor structure for use
 354  */
 355 void lustre_lnet_init_nw_descr(struct lnet_dlc_network_descr *nw_descr);
 356
 357 /*
 358  * lustre_lnet_parse_interfaces
 359  *      prase an interface string and populate descriptor structures
 360  *              intf_str - interface string of the format
 361  *                      <intf>[<expr>], <intf>[<expr>],..
 362  *              nw_descr - network descriptor to populate
 363  *              init - True to initialize nw_descr
 364  */
 365 int lustre_lnet_parse_interfaces(char *intf_str,
 366                                  struct lnet_dlc_network_descr *nw_descr);
 367
 368 /*
 369  * lustre_lnet_parse_nids
 370  *      Parse a set of nids into a locally allocated array and return the
 371  *      pointer of the array to the caller. The caller is responsible for
 372  *      freeing the array. If an initial array is provided then copy over
 373  *      the contents of that array into the new array and append to it the
 374  *      new content.
 375  *      The nids can be of the form "nid [,nid, nid, nid]"
 376  *              nids: nids string to be parsed
 377  *              array: initial array of content
 378  *              size: num of elements in the array
 379  *              out_array: [OUT] new allocated array.
 380  *      Returns size of array
 381  *              sets the out_array to NULL on failure.
 382  */
 383 int lustre_lnet_parse_nids(char *nids, char **array, int size,
 384                            char ***out_array);
 385
 386 #endif /* LIB_LNET_CONFIG_API_H */