LNetConfigurationApi.xml

   1 <?xml version='1.0' encoding='UTF-8'?><chapter xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US" xml:id="lnetconfigurationapi">
   2   <title xml:id="lnetconfigurationapi.title">LNet Configuration C-API</title>
   3   <para>This section describes the LNet Configuration C-API library. This
   4   API allows the developer to programatically configure LNet. It provides
   5   APIs to add, delete and show LNet configuration items listed below.  The
   6   API utilizes IOCTL to communicate with the kernel.  Changes take effect
   7   immediately and do not require restarting LNet. API calls are
   8   synchronous</para>
   9   <para>
  10     <itemizedlist>
  11       <listitem>
  12         <para>Configuring LNet</para>
  13       </listitem>
  14       <listitem>
  15         <para>Enabling/Disabling routing</para>
  16       </listitem>
  17       <listitem>
  18         <para>Adding/removing/showing Routes</para>
  19       </listitem>
  20       <listitem>
  21         <para>Adding/removing/showing Networks</para>
  22       </listitem>
  23       <listitem>
  24         <para>Configuring Router Buffer Pools</para>
  25       </listitem>
  26     </itemizedlist>
  27   </para>
  28     <section remap="h5">
  29       <title><indexterm>
  30           <primary>LNet</primary>
  31           <secondary>capi general information</secondary>
  32         </indexterm>General API Information</title>
  33       <para/>
  34       <section>
  35         <title><indexterm>
  36             <primary>LNet</primary>
  37             <secondary>capi return code</secondary>
  38           </indexterm>API Return Code</title>
  39         <screen>LUSTRE_CFG_RC_NO_ERR                 0
  40 LUSTRE_CFG_RC_BAD_PARAM             -1
  41 LUSTRE_CFG_RC_MISSING_PARAM         -2
  42 LUSTRE_CFG_RC_OUT_OF_RANGE_PARAM    -3
  43 LUSTRE_CFG_RC_OUT_OF_MEM            -4
  44 LUSTRE_CFG_RC_GENERIC_ERR           -5</screen>
  45       </section>
  46       <section>
  47         <title><indexterm>
  48             <primary>LNet</primary>
  49             <secondary>capi input params</secondary>
  50           </indexterm>API Common Input Parameters</title>
  51         <para>All APIs take as input a sequence number. This is a number
  52         that's assigned by the caller of the API, and is returned in the
  53         YAML error return block. It is used to associate the request with
  54         the response. It is especially useful when configuring via the
  55         YAML interface, since typically the YAML interface is used to
  56         configure multiple items. In the
  57         return Error block, it is desired to know which items were
  58         configured properly and which were not configured properly. The
  59         sequence number achieves this purpose.</para>
  60       </section>
  61       <section>
  62         <title><indexterm>
  63             <primary>LNet</primary>
  64             <secondary>capi output params</secondary>
  65           </indexterm>API Common Output Parameters</title>
  66         <para/>
  67         <section>
  68           <title><indexterm>
  69             <primary>LNet</primary>
  70             <secondary>cyaml</secondary>
  71           </indexterm>Internal YAML Representation (cYAML)</title>
  72           <para>Once a YAML block is parsed it needs to be stored
  73           structurally in order to facilitate passing it to different
  74           functions, querying it and printing it. Also it is required to
  75           be able to build this internal representation from data returned
  76           from the kernel and return it to the caller, which can query and
  77           print it. This structure
  78             representation is used for the Error and Show API Out
  79             parameters. For this YAML is internally represented via this
  80             structure:</para>
  81           <screen>typedef enum {
  82     EN_YAML_TYPE_FALSE = 0,
  83     EN_YAML_TYPE_TRUE,
  84     EN_YAML_TYPE_NULL,
  85     EN_YAML_TYPE_NUMBER,
  86     EN_YAML_TYPE_STRING,
  87     EN_YAML_TYPE_ARRAY,
  88     EN_YAML_TYPE_OBJECT
  89 } cYAML_object_type_t;
  90
  91 typedef struct cYAML {
  92     /* next/prev allow you to walk array/object chains. */
  93     struct cYAML *cy_next, *cy_prev;
  94     /* An array or object item will have a child pointer pointing
  95        to a chain of the items in the array/object. */
  96     struct cYAML *cy_child;
  97     /* The type of the item, as above. */
  98     cYAML_object_type_t cy_type;
  99     /* The item's string, if type==EN_YAML_TYPE_STRING */
 100     char *cy_valuestring;
 101     /* The item's number, if type==EN_YAML_TYPE_NUMBER */
 102     int cy_valueint;
 103     /* The item's number, if type==EN_YAML_TYPE_NUMBER */
 104     double cy_valuedouble;
 105     /* The item's name string, if this item is the child of,
 106        or is in the list of subitems of an object. */
 107     char *cy_string;
 108     /* user data which might need to be tracked per object */
 109     void *cy_user_data;
 110 } cYAML;</screen>
 111         </section>
 112         <section>
 113           <title><indexterm>
 114               <primary>LNet</primary>
 115               <secondary>error block</secondary>
 116             </indexterm>Error Block</title>
 117           <para>All APIs return a cYAML error block. This error block has
 118           the following format, when it's printed out. All configuration
 119           errors shall be represented in a YAML sequence</para>
 120           <screen>&lt;cmd>:
 121   - &lt;entity>:
 122     errno: &lt;error number>
 123     seqno: &lt;sequence number>
 124     descr: &lt;error description>
 125
 126 Example:
 127 add:
 128   - route
 129       errno: -2
 130       seqno: 1
 131       descr: Missing mandatory parameter(s) - network</screen>
 132         </section>
 133         <section>
 134           <title><indexterm>
 135               <primary>LNet</primary>
 136               <secondary>show block</secondary>
 137             </indexterm>Show Block</title>
 138           <para>All Show APIs return a cYAML show block. This show block
 139           represents the information requested in YAML format. Each
 140           configuration item has its own YAML syntax. The YAML syntax of
 141           all supported configuration items is described later in this
 142           document. Below is an example of a show block:</para>
 143           <screen>net:
 144     - nid: 192.168.206.130@tcp4
 145       status: up
 146       interfaces:
 147           0: eth0
 148       tunables:
 149           peer_timeout: 10
 150           peer_credits: 8
 151           peer_buffer_credits: 30
 152           credits: 40</screen>
 153         </section>
 154       </section>
 155     </section>
 156     <section>
 157       <title><indexterm>
 158           <primary>LNet</primary>
 159           <secondary>show block</secondary>
 160         </indexterm>The LNet Configuration C-API</title>
 161       <para/>
 162       <section>
 163         <title><indexterm>
 164             <primary>LNet</primary>
 165             <secondary>lustre_lnet_config_ni_system</secondary>
 166           </indexterm>Configuring LNet</title>
 167         <para/>
 168         <screen>
 169 /*
 170  * lustre_lnet_config_ni_system
 171  *   Initialize/Uninitialize the LNet NI system.
 172  *
 173  *   up - whether to init or uninit the system
 174  *   load_ni_from_mod - load NI from mod params.
 175  *   seq_no - sequence number of the request
 176  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by
 177  *            caller
 178  */
 179 int lustre_lnet_config_ni_system(bool up, bool load_ni_from_mod,
 180                                  int seq_no, struct cYAML **err_rc);</screen>
 181         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 182         <para>IOC_LIBCFS_CONFIGURE or IOC_LIBCFS_UNCONFIGURE</para>
 183         <para><emphasis role="bold">Description:</emphasis></para>
 184         <para><emphasis role="bold">Configuring LNet</emphasis>
 185         </para>
 186         <para>Initialize LNet internals and load any networks specified in the module
 187         parameter if <literal>load_ni_from_mod</literal> is set.  Otherwise do not
 188         load any network interfaces.</para>
 189         <para><emphasis role="bold">Unconfiguring LNet</emphasis></para>
 190         <para>Bring down LNet and clean up network itnerfaces, routes and all LNet
 191         internals.</para>
 192         <para><emphasis role="bold">Return Value</emphasis></para>
 193         <para>0: if success</para>
 194         <para>-errno: if failure</para>
 195       </section>
 196       <section>
 197         <title><indexterm>
 198             <primary>LNet</primary>
 199             <secondary>lustre_lnet_enable_routing</secondary>
 200           </indexterm>Enabling and Disabling Routing</title>
 201         <para/>
 202         <screen>/*
 203  * lustre_lnet_enable_routing
 204  *   Send down an IOCTL to enable or disable routing
 205  *
 206  *   enable - 1 to enable routing, 0 to disable routing
 207  *   seq_no - sequence number of the request
 208  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 209  */
 210 extern int lustre_lnet_enable_routing(int enable,
 211                                       int seq_no,
 212                                       cYAML **err_rc);</screen>
 213         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 214         <para>IOC_LIBCFS_ENABLE_RTR </para>
 215         <para><emphasis role="bold">Description:</emphasis></para>
 216         <para><emphasis role="bold">Enabling Routing</emphasis>
 217         </para>
 218         <para>The router buffer pools are allocated using the default values. Internally the node
 219           is then flagged as a Router node. The node can be used as a router from this
 220           point on.</para>
 221         <para><emphasis role="bold">Disabling Routing</emphasis></para>
 222         <para>The unused router buffer pools are freed. Buffers currently
 223         in use are not freed until they are returned to the unused list.
 224         Internally the node routing flag is turned off. Any subsequent
 225         messages not destined to this node are dropped. </para>
 226         <para><emphasis role="bold">Enabling Routing on an already enabled
 227         node, or vice versa</emphasis></para>
 228         <para>In both these cases the LNet Kernel module ignores this request. </para>
 229         <para><emphasis role="bold">Return Value</emphasis></para>
 230         <para>-ENOMEM: if there is no memory to allocate buffer pools</para>
 231         <para>0: if success</para>
 232       </section>
 233       <section>
 234         <title><indexterm>
 235             <primary>LNet</primary>
 236             <secondary>lustre_lnet_config_route</secondary>
 237           </indexterm>Adding Routes</title>
 238         <para/>
 239         <screen>/*
 240  * lustre_lnet_config_route
 241  *   Send down an IOCTL to the kernel to configure the route
 242  *
 243  *   nw - network
 244  *   gw - gateway
 245  *   hops - number of hops passed down by the user
 246  *   prio - priority of the route
 247  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 248  */
 249 extern int lustre_lnet_config_route(char *nw, char *gw,
 250                     int hops, int prio,
 251                     int seq_no,
 252                     cYAML **err_rc);</screen>
 253         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 254         <para>IOC_LIBCFS_ADD_ROUTE</para>
 255         <para><emphasis role="bold">Description:</emphasis></para>
 256         <para>The LNet Kernel module adds this route to the list of
 257         existing routes, if one doesn't already exist. If hop parameter is
 258         not specified (IE: -1) then the hop count is set to 1.  If the
 259         priority parameter is not specified (IE: -1) then the priority is
 260         set to 0. All routes with the same hop and priority are used in
 261         round robin. Routes with lower number of hops and/or higher
 262         priority are preferred. 0 is the highest priority.</para>
 263         <para>If a route already exists the request to add the same route is ignored.</para>
 264         <para><emphasis role="bold">Return Value</emphasis></para>
 265         <para>-EINVAL: if the network of the route is local</para>
 266         <para>-ENOMEM: if there is no memory</para>
 267         <para>-EHOSTUNREACH: if the host is not on a local network</para>
 268         <para>0: if success</para>
 269       </section>
 270       <section>
 271         <title><indexterm>
 272             <primary>LNet</primary>
 273             <secondary>lustre_lnet_del_route</secondary>
 274           </indexterm>Deleting Routes</title>
 275         <para/>
 276         <screen>/*
 277  * lustre_lnet_del_route
 278  *   Send down an IOCTL to the kernel to delete a route
 279  *
 280  *   nw - network
 281  *   gw - gateway
 282  */
 283 extern int lustre_lnet_del_route(char *nw, char *gw,
 284                  int seq_no,
 285                  cYAML **err_rc);</screen>
 286         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 287         <para>IOC_LIBCFS_DEL_ROUTE</para>
 288         <para><emphasis role="bold">Description:</emphasis></para>
 289         <para>LNet will remove the route which matches the network and gateway passed in. If
 290           no route matches, then the operation fails with an appropriate error number.</para>
 291         <para><emphasis role="bold">Return Value</emphasis></para>
 292         <para>-ENOENT: if the entry being deleted doesn't exist</para>
 293         <para>0: if success</para>
 294       </section>
 295       <section>
 296         <title><indexterm>
 297             <primary>LNet</primary>
 298             <secondary>lustre_lnet_show_route</secondary>
 299           </indexterm>Showing Routes</title>
 300         <para/>
 301         <screen>/*
 302  * lustre_lnet_show_route
 303  *   Send down an IOCTL to the kernel to show routes
 304  *   This function will get one route at a time and filter according to
 305  *   provided parameters. If no filter is provided then it will dump all
 306  *   routes that are in the system.
 307  *
 308  *   nw - network.  Optional.  Used to filter output
 309  *   gw - gateway. Optional. Used to filter ouptut
 310  *   hops - number of hops passed down by the user
 311  *          Optional.  Used to filter output.
 312  *   prio - priority of the route.  Optional.  Used to filter output.
 313  *   detail - flag to indicate whether detail output is required
 314  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 315  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 316  */
 317 extern int lustre_lnet_show_route(char *nw, char *gw,
 318                   int hops, int prio, int detail,
 319                   int seq_no,
 320                   cYAML **show_rc,
 321                   cYAML **err_rc);</screen>
 322         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 323         <para>IOC_LIBCFS_GET_ROUTE</para>
 324         <para><emphasis role="bold">Description:</emphasis></para>
 325         <para>The routes are fetched from the kernel one by one and packed
 326         in a cYAML block, after filtering according to the parameters
 327         passed in. The cYAML block is then returned to the caller of the
 328         API.</para>
 329         <para>An example with the detail parameter set to 1</para>
 330         <screen>route:
 331     net: tcp5
 332     gateway: 192.168.205.130@tcp
 333     hop: 1.000000
 334     priority: 0.000000
 335     state: up</screen>
 336         <para>An Example with the detail parameter set to 0</para>
 337         <screen>route:
 338     net: tcp5
 339     gateway: 192.168.205.130@tcp</screen>
 340         <para><emphasis role="bold">Return Value</emphasis></para>
 341         <para>-ENOMEM: If no memory</para>
 342         <para>0: if success</para>
 343       </section>
 344       <section>
 345         <title><indexterm>
 346             <primary>LNet</primary>
 347             <secondary>lustre_lnet_config_net</secondary>
 348           </indexterm>Adding a Network Interface</title>
 349         <para/>
 350         <screen>/*
 351  * lustre_lnet_config_net
 352  *   Send down an IOCTL to configure a network.
 353  *
 354  *   net - the network name
 355  *   intf - the interface of the network of the form net_name(intf)
 356  *   peer_to - peer timeout
 357  *   peer_cr - peer credit
 358  *   peer_buf_cr - peer buffer credits
 359  *       - the above are LND tunable parameters and are optional
 360  *   credits - network interface credits
 361  *   smp - cpu affinity
 362  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 363  */
 364 extern int lustre_lnet_config_net(char *net,
 365                   char *intf,
 366                   int peer_to,
 367                   int peer_cr,
 368                   int peer_buf_cr,
 369                   int credits,
 370                   char *smp,
 371                   int seq_no,
 372                   cYAML **err_rc);</screen>
 373         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 374         <para>IOC_LIBCFS_ADD_NET</para>
 375         <para><emphasis role="bold">Description:</emphasis></para>
 376         <para>A new network is added and initialized. This has the same
 377         effect as configuring a network from the module parameters. The
 378         API allows the specification of network parameters such as the
 379         peer timeout, peer credits, peer buffer credits and credits. The
 380         CPU affinity of the network interface being added can also be
 381         specified. These parameters become
 382         network specific under Dynamic LNet Configuration (DLC), as
 383         opposed to being per LND as it was previously.</para>
 384         <para>If an already existing network is added the request is ignored.</para>
 385         <para><emphasis role="bold">Return Value</emphasis></para>
 386         <para>-EINVAL: if the network passed in is not recognized.</para>
 387         <para>-ENOMEM: if no memory</para>
 388         <para>0: success</para>
 389       </section>
 390       <section>
 391         <title><indexterm>
 392             <primary>LNet</primary>
 393             <secondary>lustre_lnet_del_net</secondary>
 394           </indexterm>Deleting a Network Interface</title>
 395         <para/>
 396         <screen>/*
 397  * lustre_lnet_del_net
 398  *   Send down an IOCTL to delete a network.
 399  *
 400  *   nw - network to delete.
 401  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 402  */
 403 extern int lustre_lnet_del_net(char *nw,
 404                    int seq_no,
 405                    cYAML **err_rc);</screen>
 406         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 407         <para>IOC_LIBCFS_DEL_NET</para>
 408         <para><emphasis role="bold">Description:</emphasis></para>
 409         <para>The network interface specified is deleted. All resources
 410         associated with this network interface are freed. All routes going
 411         over that Network Interface are cleaned up.</para>
 412         <para>If a non existent network is deleted then the call return -EINVAL.</para>
 413         <para><emphasis role="bold">Return Value</emphasis></para>
 414         <para>-EINVAL: if the request references a non-existent network.</para>
 415         <para>0: success</para>
 416       </section>
 417       <section>
 418         <title><indexterm>
 419             <primary>LNet</primary>
 420             <secondary>lustre_lnet_show_net</secondary>
 421           </indexterm>Showing Network Interfaces</title>
 422         <para/>
 423         <screen>/*
 424  * lustre_lnet_show_net
 425  *   Send down an IOCTL to show networks.
 426  *   This function will use the nw paramter to filter the output.  If it's
 427  *   not provided then all networks are listed.
 428  *
 429  *   nw - network to show.  Optional.  Used to filter output.
 430  *   detail - flag to indicate if we require detail output.
 431  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 432  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 433  */
 434 extern int lustre_lnet_show_net(char *nw, int detail,
 435                 int seq_no,
 436                 cYAML **show_rc,
 437                 cYAML **err_rc);</screen>
 438         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 439         <para>IOC_LIBCFS_GET_NET</para>
 440         <para><emphasis role="bold">Description:</emphasis></para>
 441         <para>The network interfaces are queried one at a time from the
 442         kernel and packed in a cYAML block, after filtering on the network
 443         (EX: tcp). If the detail field is set to 1, then the tunable
 444         section of the show block is included in the return.</para>
 445         <para>An example of the detailed output</para>
 446         <screen>net:
 447     nid: 192.168.206.130@tcp4
 448     status: up
 449     interfaces:
 450         intf-0: eth0
 451     tunables:
 452         peer_timeout: 10
 453         peer_credits: 8
 454         peer_buffer_credits: 30
 455         credits: 40</screen>
 456         <para>An example of none detailed output</para>
 457         <screen>net:
 458     nid: 192.168.206.130@tcp4
 459     status: up
 460     interfaces:
 461         intf-0: eth0</screen>
 462         <para><emphasis role="bold">Return Value</emphasis></para>
 463         <para>-ENOMEM: if no memory to allocate the error or show blocks.</para>
 464         <para>0: success</para>
 465       </section>
 466       <section>
 467         <title><indexterm>
 468             <primary>LNet</primary>
 469             <secondary>lustre_lnet_config_buf</secondary>
 470           </indexterm>Adjusting Router Buffer Pools</title>
 471         <para/>
 472         <screen>/*
 473  * lustre_lnet_config_buf
 474  *   Send down an IOCTL to configure buffer sizes.  A value of 0 means
 475  *   default that particular buffer to default size. A value of -1 means
 476  *   leave the value of the buffer unchanged.
 477  *
 478  *   tiny - tiny buffers
 479  *   small - small buffers
 480  *   large - large buffers.
 481  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 482  */
 483 extern int lustre_lnet_config_buf(int tiny,
 484                   int small,
 485                   int large,
 486                   int seq_no,
 487                   cYAML **err_rc);</screen>
 488         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 489         <para>IOC_LIBCFS_ADD_BUF</para>
 490         <para><emphasis role="bold">Description:</emphasis></para>
 491         <para>This API is used to configure the tiny, small and large
 492         router buffers dynamically.  These buffers are used to buffer
 493         messages which are being routed to other nodes. The minimum value
 494         of these buffers per CPT are:</para>
 495         <screen>#define LNET_NRB_TINY_MIN     512
 496 #define LNET_NRB_SMALL_MIN    4096
 497 #define LNET_NRB_LARGE_MIN    256</screen>
 498         <para>The default values of these buffers are:</para>
 499         <screen>#define LNET_NRB_TINY         (LNET_NRB_TINY_MIN * 4)
 500 #define LNET_NRB_SMALL        (LNET_NRB_SMALL_MIN * 4)
 501 #define LNET_NRB_LARGE        (LNET_NRB_LARGE_MIN * 4)</screen>
 502         <para>These default value is divided evenly across all CPTs. However, each CPT can only go
 503           as low as the minimum.</para>
 504         <para>Multiple calls to this API with the same values has no effect</para>
 505         <para><emphasis role="bold">Return Value</emphasis></para>
 506         <para>-ENOMEM: if no memory to allocate buffer pools.</para>
 507         <para>0: success</para>
 508       </section>
 509       <section>
 510         <title><indexterm>
 511           <primary>LNet</primary>
 512           <secondary>lustre_lnet_show_buf</secondary>
 513         </indexterm>Showing Routing information</title>
 514         <para/>
 515         <screen>/*
 516  * lustre_lnet_show_routing
 517  *   Send down an IOCTL to dump buffers and routing status
 518  *   This function is used to dump buffers for all CPU partitions.
 519  *
 520  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 521  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 522  */
 523 extern int lustre_lnet_show_routing(int seq_no, struct cYAML **show_rc,
 524                                     struct cYAML **err_rc);
 525 </screen>
 526         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 527         <para>IOC_LIBCFS_GET_BUF</para>
 528         <para><emphasis role="bold">Description:</emphasis></para>
 529         <para>This API returns a cYAML block describing the values of each of the following per
 530           CPT:</para>
 531         <para>
 532           <orderedlist>
 533             <listitem>
 534               <para>The number of pages per buffer. This is a constant.</para>
 535             </listitem>
 536             <listitem>
 537               <para>The number of allocated buffers. This is a constant.</para>
 538             </listitem>
 539             <listitem>
 540               <para>The number of buffer credits . This is a real-time value of the number of buffer
 541                 credits currently available. If this value is negative, that indicates the number of
 542                 queued messages.</para>
 543             </listitem>
 544             <listitem>
 545               <para>The lowest number of credits ever reached in the system. This is historical
 546                 data.</para>
 547             </listitem>
 548           </orderedlist>
 549         </para>
 550         <para>The show block also returns the status of routing, whether enabled, or
 551         disabled.</para>
 552         <para>An exmaple YAML block</para>
 553         <screen>routing:
 554     - cpt[0]:
 555           tiny:
 556               npages: 0
 557               nbuffers: 2048
 558               credits: 2048
 559               mincredits: 2048
 560           small:
 561               npages: 1
 562               nbuffers: 16384
 563               credits: 16384
 564               mincredits: 16384
 565           large:
 566               npages: 256
 567               nbuffers: 1024
 568               credits: 1024
 569               mincredits: 1024
 570     - enable: 1</screen>
 571         <para><emphasis role="bold">Return Value</emphasis></para>
 572         <para>-ENOMEM: if no memory to allocate the show or error block.</para>
 573         <para>0: success</para>
 574       </section>
 575       <section>
 576         <title><indexterm>
 577             <primary>LNet</primary>
 578             <secondary>lustre_lnet_show stats</secondary>
 579           </indexterm>Showing LNet Traffic Statistics</title>
 580         <para/>
 581         <screen>/*
 582  * lustre_lnet_show_stats
 583  *   Shows internal LNet statistics.  This is useful to display the
 584  *   current LNet activity, such as number of messages route, etc
 585  *
 586  *     seq_no - sequence number of the command
 587  *     show_rc - YAML structure of the resultant show
 588  *     err_rc - YAML strucutre of the resultant return code.
 589  */
 590 extern int lustre_lnet_show_stats(int seq_no, cYAML **show_rc,
 591                   cYAML **err_rc);</screen>
 592         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 593         <para>IOC_LIBCFS_GET_LNET_STATS</para>
 594         <para><emphasis role="bold">Description:</emphasis></para>
 595         <para>This API returns a cYAML block describing the LNet traffic
 596         statistics. Statistics are continuously incremented by LNet while
 597         it's alive.  This API retuns the statistics at the time of the API
 598         call. The statistics include the following</para>
 599         <para>
 600           <orderedlist>
 601             <listitem>
 602               <para>Number of messages allocated</para>
 603             </listitem>
 604             <listitem>
 605               <para>Maximum number of messages in the system</para>
 606             </listitem>
 607             <listitem>
 608               <para>Errors allocating or sending messages</para>
 609             </listitem>
 610             <listitem>
 611               <para>Cumulative number of messages sent</para>
 612             </listitem>
 613             <listitem>
 614               <para>Cumulative number of messages received</para>
 615             </listitem>
 616             <listitem>
 617               <para>Cumulative number of messages routed</para>
 618             </listitem>
 619             <listitem>
 620               <para>Cumulative number of messages dropped</para>
 621             </listitem>
 622             <listitem>
 623               <para>Cumulative number of bytes sent</para>
 624             </listitem>
 625             <listitem>
 626               <para>Cumulative number of bytes received</para>
 627             </listitem>
 628             <listitem>
 629               <para>Cumulative number of bytes routed</para>
 630             </listitem>
 631             <listitem>
 632               <para>Cumulative number of bytes dropped</para>
 633             </listitem>
 634           </orderedlist>
 635         </para>
 636         <para>An exmaple YAML block</para>
 637         <screen>statistics:
 638     msgs_alloc: 0
 639     msgs_max: 0
 640     errors: 0
 641     send_count: 0
 642     recv_count: 0
 643     route_count: 0
 644     drop_count: 0
 645     send_length: 0
 646     recv_length: 0
 647     route_length: 0
 648     drop_length: 0</screen>
 649         <para><emphasis role="bold">Return Value</emphasis></para>
 650         <para>-ENOMEM: if no memory to allocate the show or error block.</para>
 651         <para>0: success</para>
 652       </section>
 653       <section>
 654         <title><indexterm>
 655             <primary>LNet</primary>
 656             <secondary>lustre_yaml</secondary>
 657           </indexterm>Adding/Deleting/Showing Parameters through a YAML Block</title>
 658         <para/>
 659         <screen>/*
 660  * lustre_yaml_config
 661  *   Parses the provided YAML file and then calls the specific APIs
 662  *   to configure the entities identified in the file
 663  *
 664  *   f - YAML file
 665  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 666  */
 667 extern int lustre_yaml_config(char *f, cYAML **err_rc);
 668
 669 /*
 670  * lustre_yaml_del
 671  *   Parses the provided YAML file and then calls the specific APIs
 672  *   to delete the entities identified in the file
 673  *
 674  *   f - YAML file
 675  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 676  */
 677 extern int lustre_yaml_del(char *f, cYAML **err_rc);
 678
 679 /*
 680  * lustre_yaml_show
 681  *   Parses the provided YAML file and then calls the specific APIs
 682  *   to show the entities identified in the file
 683  *
 684  *   f - YAML file
 685  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 686  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 687  */
 688 extern int lustre_yaml_show(char *f,
 689                 cYAML **show_rc,
 690                 cYAML **err_rc);</screen>
 691         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 692         <para>Depends on the entity being configured</para>
 693         <para><emphasis role="bold">Description:</emphasis></para>
 694         <para>These APIs add/remove/show the parameters specified in the
 695         YAML file respectively. The entities don't have to be uniform.
 696         Multiple different entities can be added/removed/showed in one
 697         YAML block.</para>
 698         <para>An example YAML block</para>
 699         <screen>---
 700 net:
 701     - nid: 192.168.206.132@tcp
 702       status: up
 703       interfaces:
 704           0: eth3
 705       tunables:
 706           peer_timeout: 180
 707           peer_credits: 8
 708           peer_buffer_credits: 0
 709           credits: 256
 710           SMP: "[0]"
 711 route:
 712    - net: tcp6
 713      gateway: 192.168.29.1@tcp
 714      hop: 4
 715      detail: 1
 716      seq_no: 3
 717    - net: tcp7
 718      gateway: 192.168.28.1@tcp
 719      hop: 9
 720      detail: 1
 721      seq_no: 4
 722 buffer:
 723    - tiny: 1024
 724      small: 2000
 725      large: 512
 726 ...</screen>
 727         <para><emphasis role="bold">Return Value</emphasis></para>
 728         <para>Return value will correspond to the return value of the API
 729         that will be called to operate on the configuration item, as
 730         described in previous sections</para>
 731       </section>
 732       <section>
 733         <title><indexterm>
 734             <primary>DLC</primary>
 735             <secondary>Code Example</secondary>
 736           </indexterm>Adding a route code example</title>
 737         <para/>
 738         <screen>
 739 int main(int argc, char **argv)
 740 {
 741         char *network = NULL, *gateway = NULL;
 742         long int hop = -1, prio = -1;
 743         struct cYAML *err_rc = NULL;
 744         int rc, opt;
 745         optind = 0;
 746
 747         const char *const short_options = "n:g:c:p:h";
 748         const struct option long_options[] = {
 749                 { "net", 1, NULL, 'n' },
 750                 { "gateway", 1, NULL, 'g' },
 751                 { "hop-count", 1, NULL, 'c' },
 752                 { "priority", 1, NULL, 'p' },
 753                 { "help", 0, NULL, 'h' },
 754                 { NULL, 0, NULL, 0 },
 755         };
 756
 757         while ((opt = getopt_long(argc, argv, short_options,
 758                                    long_options, NULL)) != -1) {
 759                 switch (opt) {
 760                 case 'n':
 761                         network = optarg;
 762                         break;
 763                 case 'g':
 764                         gateway = optarg;
 765                         break;
 766                 case 'c':
 767                         rc = parse_long(optarg, &amp;hop);
 768                         if (rc != 0) {
 769                                 /* ignore option */
 770                                 hop = -1;
 771                                 continue;
 772                         }
 773                         break;
 774                 case 'p':
 775                         rc = parse_long(optarg, &amp;prio);
 776                         if (rc != 0) {
 777                                 /* ingore option */
 778                                 prio = -1;
 779                                 continue;
 780                         }
 781                         break;
 782                 case 'h':
 783                         print_help(route_cmds, "route", "add");
 784                         return 0;
 785                 default:
 786                         return 0;
 787                 }
 788         }
 789
 790         rc = lustre_lnet_config_route(network, gateway, hop, prio, -1, &amp;err_rc);
 791
 792         if (rc != LUSTRE_CFG_RC_NO_ERR)
 793                 cYAML_print_tree2file(stderr, err_rc);
 794
 795         cYAML_free_tree(err_rc);
 796
 797         return rc;
 798 }       </screen>
 799         <para>For other code examples refer to
 800         <screen>lnet/utils/lnetctl.c</screen></para>
 801       </section>
 802     </section>
 803 </chapter>