LNetConfigurationApi.xml

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