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 hop parameter is
 261         not specified (IE: -1) then the hop count is set to 1.  If the
 262         priority parameter is not specified (IE: -1) then the priority is
 263         set to 0. All routes with the same hop and priority are used in
 264         round robin. Routes with lower number of hops and/or higher
 265         priority are preferred. 0 is the highest priority.</para>
 266         <para>If a route already exists the request to add the same route is ignored.</para>
 267         <para><emphasis role="bold">Return Value</emphasis></para>
 268         <para>-EINVAL: if the network of the route is local</para>
 269         <para>-ENOMEM: if there is no memory</para>
 270         <para>-EHOSTUNREACH: if the host is not on a local network</para>
 271         <para>0: if success</para>
 272       </section>
 273       <section>
 274         <title><indexterm>
 275             <primary>LNet</primary>
 276             <secondary>lustre_lnet_del_route</secondary>
 277           </indexterm>Deleting Routes</title>
 278         <para/>
 279         <screen>/*
 280  * lustre_lnet_del_route
 281  *   Send down an IOCTL to the kernel to delete a route
 282  *
 283  *   nw - network
 284  *   gw - gateway
 285  */
 286 extern int lustre_lnet_del_route(char *nw, char *gw,
 287                  int seq_no,
 288                  cYAML **err_rc);</screen>
 289         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 290         <para>IOC_LIBCFS_DEL_ROUTE</para>
 291         <para><emphasis role="bold">Description:</emphasis></para>
 292         <para>LNet will remove the route which matches the network and gateway passed in. If
 293           no route matches, then the operation fails with an appropriate error number.</para>
 294         <para><emphasis role="bold">Return Value</emphasis></para>
 295         <para>-ENOENT: if the entry being deleted doesn't exist</para>
 296         <para>0: if success</para>
 297       </section>
 298       <section>
 299         <title><indexterm>
 300             <primary>LNet</primary>
 301             <secondary>lustre_lnet_show_route</secondary>
 302           </indexterm>Showing Routes</title>
 303         <para/>
 304         <screen>/*
 305  * lustre_lnet_show_route
 306  *   Send down an IOCTL to the kernel to show routes
 307  *   This function will get one route at a time and filter according to
 308  *   provided parameters. If no filter is provided then it will dump all
 309  *   routes that are in the system.
 310  *
 311  *   nw - network.  Optional.  Used to filter output
 312  *   gw - gateway. Optional. Used to filter ouptut
 313  *   hops - number of hops passed down by the user
 314  *          Optional.  Used to filter output.
 315  *   prio - priority of the route.  Optional.  Used to filter output.
 316  *   detail - flag to indicate whether detail output is required
 317  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 318  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 319  */
 320 extern int lustre_lnet_show_route(char *nw, char *gw,
 321                   int hops, int prio, int detail,
 322                   int seq_no,
 323                   cYAML **show_rc,
 324                   cYAML **err_rc);</screen>
 325         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 326         <para>IOC_LIBCFS_GET_ROUTE</para>
 327         <para><emphasis role="bold">Description:</emphasis></para>
 328         <para>The routes are fetched from the kernel one by one and packed
 329         in a cYAML block, after filtering according to the parameters
 330         passed in. The cYAML block is then returned to the caller of the
 331         API.</para>
 332         <para>An example with the detail parameter set to 1</para>
 333         <screen>route:
 334     net: tcp5
 335     gateway: 192.168.205.130@tcp
 336     hop: 1.000000
 337     priority: 0.000000
 338     state: up</screen>
 339         <para>An Example with the detail parameter set to 0</para>
 340         <screen>route:
 341     net: tcp5
 342     gateway: 192.168.205.130@tcp</screen>
 343         <para><emphasis role="bold">Return Value</emphasis></para>
 344         <para>-ENOMEM: If no memory</para>
 345         <para>0: if success</para>
 346       </section>
 347       <section>
 348         <title><indexterm>
 349             <primary>LNet</primary>
 350             <secondary>lustre_lnet_config_net</secondary>
 351           </indexterm>Adding a Network Interface</title>
 352         <para/>
 353         <screen>/*
 354  * lustre_lnet_config_net
 355  *   Send down an IOCTL to configure a network.
 356  *
 357  *   net - the network name
 358  *   intf - the interface of the network of the form net_name(intf)
 359  *   peer_to - peer timeout
 360  *   peer_cr - peer credit
 361  *   peer_buf_cr - peer buffer credits
 362  *       - the above are LND tunable parameters and are optional
 363  *   credits - network interface credits
 364  *   smp - cpu affinity
 365  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 366  */
 367 extern int lustre_lnet_config_net(char *net,
 368                   char *intf,
 369                   int peer_to,
 370                   int peer_cr,
 371                   int peer_buf_cr,
 372                   int credits,
 373                   char *smp,
 374                   int seq_no,
 375                   cYAML **err_rc);</screen>
 376         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 377         <para>IOC_LIBCFS_ADD_NET</para>
 378         <para><emphasis role="bold">Description:</emphasis></para>
 379         <para>A new network is added and initialized. This has the same
 380         effect as configuring a network from the module parameters. The
 381         API allows the specification of network parameters such as the
 382         peer timeout, peer credits, peer buffer credits and credits. The
 383         CPU affinity of the network interface being added can also be
 384         specified. These parameters become
 385         network specific under Dynamic LNet Configuration (DLC), as
 386         opposed to being per LND as it was previously.</para>
 387         <para>If an already existing network is added the request is ignored.</para>
 388         <para><emphasis role="bold">Return Value</emphasis></para>
 389         <para>-EINVAL: if the network passed in is not recognized.</para>
 390         <para>-ENOMEM: if no memory</para>
 391         <para>0: success</para>
 392       </section>
 393       <section>
 394         <title><indexterm>
 395             <primary>LNet</primary>
 396             <secondary>lustre_lnet_del_net</secondary>
 397           </indexterm>Deleting a Network Interface</title>
 398         <para/>
 399         <screen>/*
 400  * lustre_lnet_del_net
 401  *   Send down an IOCTL to delete a network.
 402  *
 403  *   nw - network to delete.
 404  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 405  */
 406 extern int lustre_lnet_del_net(char *nw,
 407                    int seq_no,
 408                    cYAML **err_rc);</screen>
 409         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 410         <para>IOC_LIBCFS_DEL_NET</para>
 411         <para><emphasis role="bold">Description:</emphasis></para>
 412         <para>The network interface specified is deleted. All resources
 413         associated with this network interface are freed. All routes going
 414         over that Network Interface are cleaned up.</para>
 415         <para>If a non existent network is deleted then the call return -EINVAL.</para>
 416         <para><emphasis role="bold">Return Value</emphasis></para>
 417         <para>-EINVAL: if the request references a non-existent network.</para>
 418         <para>0: success</para>
 419       </section>
 420       <section>
 421         <title><indexterm>
 422             <primary>LNet</primary>
 423             <secondary>lustre_lnet_show_net</secondary>
 424           </indexterm>Showing Network Interfaces</title>
 425         <para/>
 426         <screen>/*
 427  * lustre_lnet_show_net
 428  *   Send down an IOCTL to show networks.
 429  *   This function will use the nw paramter to filter the output.  If it's
 430  *   not provided then all networks are listed.
 431  *
 432  *   nw - network to show.  Optional.  Used to filter output.
 433  *   detail - flag to indicate if we require detail output.
 434  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 435  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 436  */
 437 extern int lustre_lnet_show_net(char *nw, int detail,
 438                 int seq_no,
 439                 cYAML **show_rc,
 440                 cYAML **err_rc);</screen>
 441         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 442         <para>IOC_LIBCFS_GET_NET</para>
 443         <para><emphasis role="bold">Description:</emphasis></para>
 444         <para>The network interfaces are queried one at a time from the
 445         kernel and packed in a cYAML block, after filtering on the network
 446         (EX: tcp). If the detail field is set to 1, then the tunable
 447         section of the show block is included in the return.</para>
 448         <para>An example of the detailed output</para>
 449         <screen>net:
 450     nid: 192.168.206.130@tcp4
 451     status: up
 452     interfaces:
 453         intf-0: eth0
 454     tunables:
 455         peer_timeout: 10
 456         peer_credits: 8
 457         peer_buffer_credits: 30
 458         credits: 40</screen>
 459         <para>An example of none detailed output</para>
 460         <screen>net:
 461     nid: 192.168.206.130@tcp4
 462     status: up
 463     interfaces:
 464         intf-0: eth0</screen>
 465         <para><emphasis role="bold">Return Value</emphasis></para>
 466         <para>-ENOMEM: if no memory to allocate the error or show blocks.</para>
 467         <para>0: success</para>
 468       </section>
 469       <section>
 470         <title><indexterm>
 471             <primary>LNet</primary>
 472             <secondary>lustre_lnet_config_buf</secondary>
 473           </indexterm>Adjusting Router Buffer Pools</title>
 474         <para/>
 475         <screen>/*
 476  * lustre_lnet_config_buf
 477  *   Send down an IOCTL to configure buffer sizes.  A value of 0 means
 478  *   default that particular buffer to default size. A value of -1 means
 479  *   leave the value of the buffer unchanged.
 480  *
 481  *   tiny - tiny buffers
 482  *   small - small buffers
 483  *   large - large buffers.
 484  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 485  */
 486 extern int lustre_lnet_config_buf(int tiny,
 487                   int small,
 488                   int large,
 489                   int seq_no,
 490                   cYAML **err_rc);</screen>
 491         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 492         <para>IOC_LIBCFS_ADD_BUF</para>
 493         <para><emphasis role="bold">Description:</emphasis></para>
 494         <para>This API is used to configure the tiny, small and large
 495         router buffers dynamically.  These buffers are used to buffer
 496         messages which are being routed to other nodes. The minimum value
 497         of these buffers per CPT are:</para>
 498         <screen>#define LNET_NRB_TINY_MIN     512
 499 #define LNET_NRB_SMALL_MIN    4096
 500 #define LNET_NRB_LARGE_MIN    256</screen>
 501         <para>The default values of these buffers are:</para>
 502         <screen>#define LNET_NRB_TINY         (LNET_NRB_TINY_MIN * 4)
 503 #define LNET_NRB_SMALL        (LNET_NRB_SMALL_MIN * 4)
 504 #define LNET_NRB_LARGE        (LNET_NRB_LARGE_MIN * 4)</screen>
 505         <para>These default value is divided evenly across all CPTs. However, each CPT can only go
 506           as low as the minimum.</para>
 507         <para>Multiple calls to this API with the same values has no effect</para>
 508         <para><emphasis role="bold">Return Value</emphasis></para>
 509         <para>-ENOMEM: if no memory to allocate buffer pools.</para>
 510         <para>0: success</para>
 511       </section>
 512       <section>
 513         <title><indexterm>
 514           <primary>LNet</primary>
 515           <secondary>lustre_lnet_show_buf</secondary>
 516         </indexterm>Showing Routing information</title>
 517         <para/>
 518         <screen>/*
 519  * lustre_lnet_show_routing
 520  *   Send down an IOCTL to dump buffers and routing status
 521  *   This function is used to dump buffers for all CPU partitions.
 522  *
 523  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 524  *   err_rc - [OUT] struct cYAML tree describing the error. Freed by caller
 525  */
 526 extern int lustre_lnet_show_routing(int seq_no, struct cYAML **show_rc,
 527                                     struct cYAML **err_rc);
 528 </screen>
 529         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 530         <para>IOC_LIBCFS_GET_BUF</para>
 531         <para><emphasis role="bold">Description:</emphasis></para>
 532         <para>This API returns a cYAML block describing the values of each of the following per
 533           CPT:</para>
 534         <para>
 535           <orderedlist>
 536             <listitem>
 537               <para>The number of pages per buffer. This is a constant.</para>
 538             </listitem>
 539             <listitem>
 540               <para>The number of allocated buffers. This is a constant.</para>
 541             </listitem>
 542             <listitem>
 543               <para>The number of buffer credits . This is a real-time value of the number of buffer
 544                 credits currently available. If this value is negative, that indicates the number of
 545                 queued messages.</para>
 546             </listitem>
 547             <listitem>
 548               <para>The lowest number of credits ever reached in the system. This is historical
 549                 data.</para>
 550             </listitem>
 551           </orderedlist>
 552         </para>
 553         <para>The show block also returns the status of routing, whether enabled, or
 554         disabled.</para>
 555         <para>An exmaple YAML block</para>
 556         <screen>routing:
 557     - cpt[0]:
 558           tiny:
 559               npages: 0
 560               nbuffers: 2048
 561               credits: 2048
 562               mincredits: 2048
 563           small:
 564               npages: 1
 565               nbuffers: 16384
 566               credits: 16384
 567               mincredits: 16384
 568           large:
 569               npages: 256
 570               nbuffers: 1024
 571               credits: 1024
 572               mincredits: 1024
 573     - enable: 1</screen>
 574         <para><emphasis role="bold">Return Value</emphasis></para>
 575         <para>-ENOMEM: if no memory to allocate the show or error block.</para>
 576         <para>0: success</para>
 577       </section>
 578       <section>
 579         <title><indexterm>
 580             <primary>LNet</primary>
 581             <secondary>lustre_lnet_show stats</secondary>
 582           </indexterm>Showing LNet Traffic Statistics</title>
 583         <para/>
 584         <screen>/*
 585  * lustre_lnet_show_stats
 586  *   Shows internal LNet statistics.  This is useful to display the
 587  *   current LNet activity, such as number of messages route, etc
 588  *
 589  *     seq_no - sequence number of the command
 590  *     show_rc - YAML structure of the resultant show
 591  *     err_rc - YAML strucutre of the resultant return code.
 592  */
 593 extern int lustre_lnet_show_stats(int seq_no, cYAML **show_rc,
 594                   cYAML **err_rc);</screen>
 595         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 596         <para>IOC_LIBCFS_GET_LNET_STATS</para>
 597         <para><emphasis role="bold">Description:</emphasis></para>
 598         <para>This API returns a cYAML block describing the LNet traffic
 599         statistics. Statistics are continuously incremented by LNet while
 600         it's alive.  This API retuns the statistics at the time of the API
 601         call. The statistics include the following</para>
 602         <para>
 603           <orderedlist>
 604             <listitem>
 605               <para>Number of messages allocated</para>
 606             </listitem>
 607             <listitem>
 608               <para>Maximum number of messages in the system</para>
 609             </listitem>
 610             <listitem>
 611               <para>Errors allocating or sending messages</para>
 612             </listitem>
 613             <listitem>
 614               <para>Cumulative number of messages sent</para>
 615             </listitem>
 616             <listitem>
 617               <para>Cumulative number of messages received</para>
 618             </listitem>
 619             <listitem>
 620               <para>Cumulative number of messages routed</para>
 621             </listitem>
 622             <listitem>
 623               <para>Cumulative number of messages dropped</para>
 624             </listitem>
 625             <listitem>
 626               <para>Cumulative number of bytes sent</para>
 627             </listitem>
 628             <listitem>
 629               <para>Cumulative number of bytes received</para>
 630             </listitem>
 631             <listitem>
 632               <para>Cumulative number of bytes routed</para>
 633             </listitem>
 634             <listitem>
 635               <para>Cumulative number of bytes dropped</para>
 636             </listitem>
 637           </orderedlist>
 638         </para>
 639         <para>An exmaple YAML block</para>
 640         <screen>statistics:
 641     msgs_alloc: 0
 642     msgs_max: 0
 643     errors: 0
 644     send_count: 0
 645     recv_count: 0
 646     route_count: 0
 647     drop_count: 0
 648     send_length: 0
 649     recv_length: 0
 650     route_length: 0
 651     drop_length: 0</screen>
 652         <para><emphasis role="bold">Return Value</emphasis></para>
 653         <para>-ENOMEM: if no memory to allocate the show or error block.</para>
 654         <para>0: success</para>
 655       </section>
 656       <section>
 657         <title><indexterm>
 658             <primary>LNet</primary>
 659             <secondary>lustre_yaml</secondary>
 660           </indexterm>Adding/Deleting/Showing Parameters through a YAML Block</title>
 661         <para/>
 662         <screen>/*
 663  * lustre_yaml_config
 664  *   Parses the provided YAML file and then calls the specific APIs
 665  *   to configure the entities identified in the file
 666  *
 667  *   f - YAML file
 668  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 669  */
 670 extern int lustre_yaml_config(char *f, cYAML **err_rc);
 671
 672 /*
 673  * lustre_yaml_del
 674  *   Parses the provided YAML file and then calls the specific APIs
 675  *   to delete the entities identified in the file
 676  *
 677  *   f - YAML file
 678  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 679  */
 680 extern int lustre_yaml_del(char *f, cYAML **err_rc);
 681
 682 /*
 683  * lustre_yaml_show
 684  *   Parses the provided YAML file and then calls the specific APIs
 685  *   to show the entities identified in the file
 686  *
 687  *   f - YAML file
 688  *   show_rc - [OUT] The show output in YAML.  Must be freed by caller.
 689  *   err_rc - [OUT] cYAML tree describing the error. Freed by caller
 690  */
 691 extern int lustre_yaml_show(char *f,
 692                 cYAML **show_rc,
 693                 cYAML **err_rc);</screen>
 694         <para><emphasis role="bold">IOCTL to Kernel:</emphasis></para>
 695         <para>Depends on the entity being configured</para>
 696         <para><emphasis role="bold">Description:</emphasis></para>
 697         <para>These APIs add/remove/show the parameters specified in the
 698         YAML file respectively. The entities don't have to be uniform.
 699         Multiple different entities can be added/removed/showed in one
 700         YAML block.</para>
 701         <para>An example YAML block</para>
 702         <screen>---
 703 net:
 704     - nid: 192.168.206.132@tcp
 705       status: up
 706       interfaces:
 707           0: eth3
 708       tunables:
 709           peer_timeout: 180
 710           peer_credits: 8
 711           peer_buffer_credits: 0
 712           credits: 256
 713           SMP: "[0]"
 714 route:
 715    - net: tcp6
 716      gateway: 192.168.29.1@tcp
 717      hop: 4
 718      detail: 1
 719      seq_no: 3
 720    - net: tcp7
 721      gateway: 192.168.28.1@tcp
 722      hop: 9
 723      detail: 1
 724      seq_no: 4
 725 buffer:
 726    - tiny: 1024
 727      small: 2000
 728      large: 512
 729 ...</screen>
 730         <para><emphasis role="bold">Return Value</emphasis></para>
 731         <para>Return value will correspond to the return value of the API
 732         that will be called to operate on the configuration item, as
 733         described in previous sections</para>
 734       </section>
 735       <section>
 736         <title><indexterm>
 737             <primary>DLC</primary>
 738             <secondary>Code Example</secondary>
 739           </indexterm>Adding a route code example</title>
 740         <para/>
 741         <screen>
 742 int main(int argc, char **argv)
 743 {
 744         char *network = NULL, *gateway = NULL;
 745         long int hop = -1, prio = -1;
 746         struct cYAML *err_rc = NULL;
 747         int rc, opt;
 748         optind = 0;
 749
 750         const char *const short_options = "n:g:c:p:h";
 751         const struct option long_options[] = {
 752                 { "net", 1, NULL, 'n' },
 753                 { "gateway", 1, NULL, 'g' },
 754                 { "hop-count", 1, NULL, 'c' },
 755                 { "priority", 1, NULL, 'p' },
 756                 { "help", 0, NULL, 'h' },
 757                 { NULL, 0, NULL, 0 },
 758         };
 759
 760         while ((opt = getopt_long(argc, argv, short_options,
 761                                    long_options, NULL)) != -1) {
 762                 switch (opt) {
 763                 case 'n':
 764                         network = optarg;
 765                         break;
 766                 case 'g':
 767                         gateway = optarg;
 768                         break;
 769                 case 'c':
 770                         rc = parse_long(optarg, &amp;hop);
 771                         if (rc != 0) {
 772                                 /* ignore option */
 773                                 hop = -1;
 774                                 continue;
 775                         }
 776                         break;
 777                 case 'p':
 778                         rc = parse_long(optarg, &amp;prio);
 779                         if (rc != 0) {
 780                                 /* ingore option */
 781                                 prio = -1;
 782                                 continue;
 783                         }
 784                         break;
 785                 case 'h':
 786                         print_help(route_cmds, "route", "add");
 787                         return 0;
 788                 default:
 789                         return 0;
 790                 }
 791         }
 792
 793         rc = lustre_lnet_config_route(network, gateway, hop, prio, -1, &amp;err_rc);
 794
 795         if (rc != LUSTRE_CFG_RC_NO_ERR)
 796                 cYAML_print_tree2file(stderr, err_rc);
 797
 798         cYAML_free_tree(err_rc);
 799
 800         return rc;
 801 }       </screen>
 802         <para>For other code examples refer to
 803         <screen>lnet/utils/lnetctl.c</screen></para>
 804       </section>
 805     </section>
 806 </chapter>
 807 <!--
 808   vim:expandtab:shiftwidth=2:tabstop=8:
 809   -->