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