Documentation/dlc.txt

   1                 ******************************************
   2                 * Overview of Dynamic LNet Configuration *
   3                 ******************************************
   4
   5 Original Authors:
   6 =================
   7 Amir Shehata <amir.shehata@intel.com>
   8
   9 Contents
  10 1. Introduction
  11         1.1 Objectives
  12         1.3 Motivation
  13         1.2 Overview
  14 2. YAML Interface
  15 3. DLC API
  16 4. LNet Backend Design
  17         4.1 router.c
  18                 4.1.1 Enabling/Disabling Routing and Router Pools
  19                 4.1.2 Configuring Router Pools
  20         4.2 api-ni.c
  21                 4.2.1 Dynamically Adding an NI
  22                 4.2.2 Dynamically Deleting an NI
  23                 4.2.3 Internal Functions
  24
  25 ===================
  26 = 1. Introduction =
  27 ===================
  28
  29 1.1 Objectives
  30 ==============
  31
  32 Dynamic LNet Configuration (DLC) strives to accomplish four objectives:
  33
  34 . Allow changes to some LNet parameters to be dynamic so they can be altered
  35   without having to stop/start LNet.
  36 . Remove the limits on how many NI's or route's which can be configured.
  37 . Work towards replacing the LNet module parameters with user space scripts
  38   (i.e. /etc/rc.d and /etc/sysconfig/network-scripts) which operate much more
  39   like conventional network config systems on Linux.
  40 . Allow sysadmins to use a command line utility for making dynamic changes to
  41   the LNet configuration.
  42
  43 1.2 Motivation
  44 ==============
  45
  46 DLC introduces a new shared library. The DLC C API Library is provided as part
  47 of the standard lustre installation. This library must be released under LGPL
  48 license to facilitate third-party development. This API will serve the
  49 following purposes:
  50
  51 . Provide a funnel for all LNet configurations. This way there isn't multiple
  52   ways to configure the same thing
  53 . Provide a C API which configures specific parameters. This C API will
  54   translate into IOCTL calls to the kernel module.
  55 . Provide a YAML interface, which ensures that YAML parsing is done in one
  56   location.
  57 . Provide more detailed return values from the kernel presented in YAML
  58   format.
  59 . Provide a set of API calls to parse out the YAML error returns if need be.
  60
  61 1.3 Overview
  62 ============
  63
  64 DLC introduces a userspace library which exposes a set of APIs to:
  65
  66 . configure/unconfigure LNet
  67 . add/delete/show routes
  68 . add/delete/show networks
  69 . set router buffers sizes
  70 . enable/disable routing
  71 . import YAML configuration
  72 . export configuration in YAML format
  73 . show peer credit information
  74
  75 DLC API uses IOCTLs to communicate with the kernel. This has the following
  76 advantage:
  77
  78 . No need to do any string parsing in the kernel
  79 . Bypass the 4K limit, since each command will be sent to the kernel
  80   separately. For example, if there are 100 routes to configure then this
  81   translates to 100 ioctls to the kernel.
  82 . Provide a more intuitive user facing interface. The user need not know how
  83   to talk to the kernel via ioctl. This will be achieved in two ways:
  84         a. The configuration can be presented in YAML syntax, as shown below
  85         b. A more traditional C API will be exported, Each translates to exactly
  86            one ioctl to the kernel module.
  87
  88 =====================
  89 = 2. YAML Interface =
  90 =====================
  91
  92 The DLC API provides functions to configure specific parameters together with
  93 higher level functions which accept a YAML formatted configuration and
  94 configure all parameters described therein.
  95
  96 To aid in parsing and building YAML stings a third party library, libyaml, is
  97 used. lnet/utils/cyaml/cyaml.c is written to interface with the libyaml
  98 library. When parsing a yaml string or file, it builds an internal tree
  99 representation of the YAML string. lnet/utils/cyaml/cyaml.c then provides
 100 functions to extract data from the tree. It also provides functions to build
 101 a YAML tree, which can then be printed textually.
 102
 103 The YAML API is used by the DLC API to parse and extract YAML configuration,
 104 and to build a YAML representation of the success or error status per DLC API.
 105
 106 ==============
 107 = 3. DLC API =
 108 ==============
 109
 110 Refer to: lnet/utils/lnetconfig/liblnetconfig.h
 111
 112 ==========================
 113 = 4. LNet Backend Design =
 114 ==========================
 115
 116 4.1 lnet/lnet/router.c
 117 =======================
 118
 119 In router.c the following three functions are used to add, delete and get a
 120 route.
 121
 122 . lnet_add_route() : adds a new route entry.
 123 . lnet_del_route() : removes an existing routing entry.
 124 . lnet_get_route() : retrieves information on an existing route.
 125
 126 These functions will be called from the ioctl handler.
 127
 128 The Router buffer pools will be controlled via the following APIs:
 129
 130 . lnet_rtrpools_enable()  : enable routing and allocate router buffers
 131 . lnet_rtrpools_disable() : disable routing and free router buffers
 132 . lnet_rtrpools_adjust()  : configure the number of router buffer pools
 133
 134 4.1.1 Enabling/Disabling Routing and Router Pools
 135 =================================================
 136
 137 lnet_rtrpools_enable()
 138 lnet_rtrpools_disable()
 139
 140 These functions will explicitly enable and disable rtrpools respectively. If the
 141 rtrpools are being enabled then the default values of the tiny, small and
 142 large buffers are used.
 143
 144     #define LNET_NRB_TINY        (LNET_NRB_TINY_MIN * 4)
 145     #define LNET_NRB_SMALL        (LNET_NRB_SMALL_MIN * 4)
 146     #define LNET_NRB_LARGE        (LNET_NRB_LARGE_MIN * 4)
 147
 148 4.1.2 Configuring Router Pools
 149 ==============================
 150
 151 lnet_rtrpools_adjust()
 152
 153 This API will set the tiny, small and large buffers. rtrpools must be enabled
 154 prior to calling this API. If not enabled, this API is a no-op.
 155
 156 Below is the behavior when adjusting the router pools:
 157
 158 . A value of 0 indicates that the default values (listed above) are used.
 159 . Each pool size will be run through the current sizing algorithm to ensure the
 160   given values are not below the minimum standards. As such, a user could get
 161   the defaults for all three pools by just passing in "0 0 0" for pool sizes.
 162 . If a pool size is being made bigger, add the new buffers to the pool checking
 163   if there are any queued messages waiting for a buffer on that pool. If so,
 164   schedule those messages to be sent with the new buffer.
 165 . If a pool size is being made smaller, change the maximum value for the number
 166   of buffers on the pool only. When the system returns buffers to the pool, it
 167   will see there are "excess" buffers on the pool and will discard the buffer
 168   rather than return it to the pool.
 169
 170 4.2 lnet/lnet/api-ni.c
 171 =======================
 172
 173 The file api-ni.c contains the interface routines for working with network
 174 interfaces. Four new routines will be added to this file to support this
 175 feature.
 176
 177 lnet_dyn_add_ni()     : adds an NI dynamically
 178 lnet_dyn_del_ni()     : deletes an NI dynamically
 179 lnet_startup_lndni()  : starts a single LND.
 180 lnet_shutdown_lndni() : shuts down a single LND.
 181
 182 4.2.1 Dynamically Adding an NI
 183 ==============================
 184
 185 lnet_dyn_add_ni()
 186
 187 This function is called to startup a network passed in through userspace as a
 188 string. This function verifies that only one network is passed in.  If more
 189 than one network is passed in, it fails with -EINVAL error number.
 190
 191 Peer timeout, peer credits, and credits are passed in as well, since DLC makes
 192 these tunable parameters configurable per network interface.
 193
 194 This function does the following:
 195
 196 . Parses the network string passed in.
 197 . Initializes a new ping info structure in preparation of adding the Network
 198   Interface.
 199 . Starts up the NI
 200 . Updates the global ping info.
 201 . If there is any failure in any of these steps, appropriate cleanup action is
 202   taken.
 203
 204 4.2.2 Dynamically Deleting an NI
 205 ================================
 206
 207 lnet_dyn_del_ni()
 208
 209 This function does the following:
 210
 211 . Allocates a new ping info for the number of networks without the one being
 212   removed.
 213 . Shuts down the NI
 214 . Updates the global ping info appropriately.
 215
 216 4.2.3 Internal Functions
 217 ========================
 218
 219 lnet_startup_lndni()
 220
 221 The code was restructured to breakup the function lnet_startup_lndnis() into
 222 two functions: lnet_startup_lndni() and lnet_startup_lndnis(). This way the
 223 new lnet_dyn_add_ni() can call lnet_startup_lndni() to startup one NI, and on
 224 standard startup lnet_startup_lndnis() can start up all NIs configured in the
 225 module parameters, by calling lnet_startup_lndni() repeatedly.
 226
 227 lnet_shutdown_lndni()
 228
 229 This function was introduced to shutdown only one NI. It coexists with the
 230 original lnet_shutdown_lndnis() which shuts down all NIs, which is needed when
 231 LNet is being unconfigured.
 232
 233 lnet_shutdown_lndni() is called from lnet_dyn_del_ni() and from
 234 lnet_startup_lndni() in case there is a failure starting the NI.
 235