lustre/include/lustre_nrs.h

   1 /*
   2  * GPL HEADER START
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License version 2 only,
   8  * as published by the Free Software Foundation.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License version 2 for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * version 2 along with this program; If not, see
  17  * http://www.gnu.org/licenses/gpl-2.0.html
  18  *
  19  * GPL HEADER END
  20  */
  21 /*
  22  * Copyright (c) 2014, Intel Corporation.
  23  *
  24  * Copyright 2012 Xyratex Technology Limited
  25  */
  26 /*
  27  *
  28  * Network Request Scheduler (NRS)
  29  *
  30  */
  31
  32 #ifndef _LUSTRE_NRS_H
  33 #define _LUSTRE_NRS_H
  34
  35 /**
  36  * \defgroup nrs Network Request Scheduler
  37  * @{
  38  */
  39 struct ptlrpc_nrs_policy;
  40 struct ptlrpc_nrs_resource;
  41 struct ptlrpc_nrs_request;
  42
  43 /**
  44  * NRS control operations.
  45  *
  46  * These are common for all policies.
  47  */
  48 enum ptlrpc_nrs_ctl {
  49         /**
  50          * Not a valid opcode.
  51          */
  52         PTLRPC_NRS_CTL_INVALID,
  53         /**
  54          * Activate the policy.
  55          */
  56         PTLRPC_NRS_CTL_START,
  57         /**
  58          * Reserved for multiple primary policies, which may be a possibility
  59          * in the future.
  60          */
  61         PTLRPC_NRS_CTL_STOP,
  62         /**
  63          * Policies can start using opcodes from this value and onwards for
  64          * their own purposes; the assigned value itself is arbitrary.
  65          */
  66         PTLRPC_NRS_CTL_1ST_POL_SPEC = 0x20,
  67 };
  68
  69 /**
  70  * NRS policy operations.
  71  *
  72  * These determine the behaviour of a policy, and are called in response to
  73  * NRS core events.
  74  */
  75 struct ptlrpc_nrs_pol_ops {
  76         /**
  77          * Called during policy registration; this operation is optional.
  78          *
  79          * \param[in,out] policy The policy being initialized
  80          */
  81         int     (*op_policy_init) (struct ptlrpc_nrs_policy *policy);
  82         /**
  83          * Called during policy unregistration; this operation is optional.
  84          *
  85          * \param[in,out] policy The policy being unregistered/finalized
  86          */
  87         void    (*op_policy_fini) (struct ptlrpc_nrs_policy *policy);
  88         /**
  89          * Called when activating a policy via lprocfs; policies allocate and
  90          * initialize their resources here; this operation is optional.
  91          *
  92          * \param[in,out] policy The policy being started
  93          * \param[in,out] arg A generic char buffer
  94          *
  95          * \see nrs_policy_start_locked()
  96          */
  97         int     (*op_policy_start) (struct ptlrpc_nrs_policy *policy,
  98                                     char *arg);
  99         /**
 100          * Called when deactivating a policy via lprocfs; policies deallocate
 101          * their resources here; this operation is optional
 102          *
 103          * \param[in,out] policy The policy being stopped
 104          *
 105          * \see nrs_policy_stop0()
 106          */
 107         void    (*op_policy_stop) (struct ptlrpc_nrs_policy *policy);
 108         /**
 109          * Used for policy-specific operations; i.e. not generic ones like
 110          * \e PTLRPC_NRS_CTL_START and \e PTLRPC_NRS_CTL_GET_INFO; analogous
 111          * to an ioctl; this operation is optional.
 112          *
 113          * \param[in,out]        policy The policy carrying out operation \a opc
 114          * \param[in]     opc    The command operation being carried out
 115          * \param[in,out] arg    An generic buffer for communication between the
 116          *                       user and the control operation
 117          *
 118          * \retval -ve error
 119          * \retval   0 success
 120          *
 121          * \see ptlrpc_nrs_policy_control()
 122          */
 123         int     (*op_policy_ctl) (struct ptlrpc_nrs_policy *policy,
 124                                   enum ptlrpc_nrs_ctl opc, void *arg);
 125
 126         /**
 127          * Called when obtaining references to the resources of the resource
 128          * hierarchy for a request that has arrived for handling at the PTLRPC
 129          * service. Policies should return -ve for requests they do not wish
 130          * to handle. This operation is mandatory.
 131          *
 132          * \param[in,out] policy  The policy we're getting resources for.
 133          * \param[in,out] nrq     The request we are getting resources for.
 134          * \param[in]     parent  The parent resource of the resource being
 135          *                        requested; set to NULL if none.
 136          * \param[out]    resp    The resource is to be returned here; the
 137          *                        fallback policy in an NRS head should
 138          *                        \e always return a non-NULL pointer value.
 139          * \param[in]  moving_req When set, signifies that this is an attempt
 140          *                        to obtain resources for a request being moved
 141          *                        to the high-priority NRS head by
 142          *                        ldlm_lock_reorder_req().
 143          *                        This implies two things:
 144          *                        1. We are under obd_export::exp_rpc_lock and
 145          *                        so should not sleep.
 146          *                        2. We should not perform non-idempotent or can
 147          *                        skip performing idempotent operations that
 148          *                        were carried out when resources were first
 149          *                        taken for the request when it was initialized
 150          *                        in ptlrpc_nrs_req_initialize().
 151          *
 152          * \retval 0, +ve The level of the returned resource in the resource
 153          *                hierarchy; currently only 0 (for a non-leaf resource)
 154          *                and 1 (for a leaf resource) are supported by the
 155          *                framework.
 156          * \retval -ve    error
 157          *
 158          * \see ptlrpc_nrs_req_initialize()
 159          * \see ptlrpc_nrs_hpreq_add_nolock()
 160          * \see ptlrpc_nrs_req_hp_move()
 161          */
 162         int     (*op_res_get) (struct ptlrpc_nrs_policy *policy,
 163                                struct ptlrpc_nrs_request *nrq,
 164                                const struct ptlrpc_nrs_resource *parent,
 165                                struct ptlrpc_nrs_resource **resp,
 166                                bool moving_req);
 167         /**
 168          * Called when releasing references taken for resources in the resource
 169          * hierarchy for the request; this operation is optional.
 170          *
 171          * \param[in,out] policy The policy the resource belongs to
 172          * \param[in] res        The resource to be freed
 173          *
 174          * \see ptlrpc_nrs_req_finalize()
 175          * \see ptlrpc_nrs_hpreq_add_nolock()
 176          * \see ptlrpc_nrs_req_hp_move()
 177          */
 178         void    (*op_res_put) (struct ptlrpc_nrs_policy *policy,
 179                                const struct ptlrpc_nrs_resource *res);
 180
 181         /**
 182          * Obtains a request for handling from the policy, and optionally
 183          * removes the request from the policy; this operation is mandatory.
 184          *
 185          * \param[in,out] policy The policy to poll
 186          * \param[in]     peek   When set, signifies that we just want to
 187          *                       examine the request, and not handle it, so the
 188          *                       request is not removed from the policy.
 189          * \param[in]     force  When set, it will force a policy to return a
 190          *                       request if it has one queued.
 191          *
 192          * \retval NULL No request available for handling
 193          * \retval valid-pointer The request polled for handling
 194          *
 195          * \see ptlrpc_nrs_req_get_nolock()
 196          */
 197         struct ptlrpc_nrs_request *
 198                 (*op_req_get) (struct ptlrpc_nrs_policy *policy, bool peek,
 199                                bool force);
 200         /**
 201          * Called when attempting to add a request to a policy for later
 202          * handling; this operation is mandatory.
 203          *
 204          * \param[in,out] policy  The policy on which to enqueue \a nrq
 205          * \param[in,out] nrq The request to enqueue
 206          *
 207          * \retval 0    success
 208          * \retval != 0 error
 209          *
 210          * \see ptlrpc_nrs_req_add_nolock()
 211          */
 212         int     (*op_req_enqueue) (struct ptlrpc_nrs_policy *policy,
 213                                    struct ptlrpc_nrs_request *nrq);
 214         /**
 215          * Removes a request from the policy's set of pending requests. Normally
 216          * called after a request has been polled successfully from the policy
 217          * for handling; this operation is mandatory.
 218          *
 219          * \param[in,out] policy The policy the request \a nrq belongs to
 220          * \param[in,out] nrq    The request to dequeue
 221          *
 222          * \see ptlrpc_nrs_req_del_nolock()
 223          */
 224         void    (*op_req_dequeue) (struct ptlrpc_nrs_policy *policy,
 225                                    struct ptlrpc_nrs_request *nrq);
 226         /**
 227          * Called after the request being carried out. Could be used for
 228          * job/resource control; this operation is optional.
 229          *
 230          * \param[in,out] policy The policy which is stopping to handle request
 231          *                       \a nrq
 232          * \param[in,out] nrq    The request
 233          *
 234          * \pre assert_spin_locked(&svcpt->scp_req_lock)
 235          *
 236          * \see ptlrpc_nrs_req_stop_nolock()
 237          */
 238         void    (*op_req_stop) (struct ptlrpc_nrs_policy *policy,
 239                                 struct ptlrpc_nrs_request *nrq);
 240         /**
 241          * Registers the policy's lprocfs interface with a PTLRPC service.
 242          *
 243          * \param[in] svc The service
 244          *
 245          * \retval 0    success
 246          * \retval != 0 error
 247          */
 248         int     (*op_lprocfs_init) (struct ptlrpc_service *svc);
 249         /**
 250          * Unegisters the policy's lprocfs interface with a PTLRPC service.
 251          *
 252          * In cases of failed policy registration in
 253          * \e ptlrpc_nrs_policy_register(), this function may be called for a
 254          * service which has not registered the policy successfully, so
 255          * implementations of this method should make sure their operations are
 256          * safe in such cases.
 257          *
 258          * \param[in] svc The service
 259          */
 260         void    (*op_lprocfs_fini) (struct ptlrpc_service *svc);
 261 };
 262
 263 /**
 264  * Policy flags
 265  */
 266 enum nrs_policy_flags {
 267         /**
 268          * Fallback policy, use this flag only on a single supported policy per
 269          * service. The flag cannot be used on policies that use
 270          * \e PTLRPC_NRS_FL_REG_EXTERN
 271          */
 272         PTLRPC_NRS_FL_FALLBACK          = (1 << 0),
 273         /**
 274          * Start policy immediately after registering.
 275          */
 276         PTLRPC_NRS_FL_REG_START         = (1 << 1),
 277         /**
 278          * This is a policy registering from a module different to the one NRS
 279          * core ships in (currently ptlrpc).
 280          */
 281         PTLRPC_NRS_FL_REG_EXTERN        = (1 << 2),
 282 };
 283
 284 /**
 285  * NRS queue type.
 286  *
 287  * Denotes whether an NRS instance is for handling normal or high-priority
 288  * RPCs, or whether an operation pertains to one or both of the NRS instances
 289  * in a service.
 290  */
 291 enum ptlrpc_nrs_queue_type {
 292         PTLRPC_NRS_QUEUE_REG    = (1 << 0),
 293         PTLRPC_NRS_QUEUE_HP     = (1 << 1),
 294         PTLRPC_NRS_QUEUE_BOTH   = (PTLRPC_NRS_QUEUE_REG | PTLRPC_NRS_QUEUE_HP)
 295 };
 296
 297 /**
 298  * NRS head
 299  *
 300  * A PTLRPC service has at least one NRS head instance for handling normal
 301  * priority RPCs, and may optionally have a second NRS head instance for
 302  * handling high-priority RPCs. Each NRS head maintains a list of available
 303  * policies, of which one and only one policy is acting as the fallback policy,
 304  * and optionally a different policy may be acting as the primary policy. For
 305  * all RPCs handled by this NRS head instance, NRS core will first attempt to
 306  * enqueue the RPC using the primary policy (if any). The fallback policy is
 307  * used in the following cases:
 308  * - when there was no primary policy in the
 309  *   ptlrpc_nrs_pol_state::NRS_POL_STATE_STARTED state at the time the request
 310  *   was initialized.
 311  * - when the primary policy that was at the
 312  *   ptlrpc_nrs_pol_state::PTLRPC_NRS_POL_STATE_STARTED state at the time the
 313  *   RPC was initialized, denoted it did not wish, or for some other reason was
 314  *   not able to handle the request, by returning a non-valid NRS resource
 315  *   reference.
 316  * - when the primary policy that was at the
 317  *   ptlrpc_nrs_pol_state::PTLRPC_NRS_POL_STATE_STARTED state at the time the
 318  *   RPC was initialized, fails later during the request enqueueing stage.
 319  *
 320  * \see nrs_resource_get_safe()
 321  * \see nrs_request_enqueue()
 322  */
 323 struct ptlrpc_nrs {
 324         spinlock_t                      nrs_lock;
 325         /** XXX Possibly replace svcpt->scp_req_lock with another lock here. */
 326         /**
 327          * List of registered policies
 328          */
 329         struct list_head                nrs_policy_list;
 330         /**
 331          * List of policies with queued requests. Policies that have any
 332          * outstanding requests are queued here, and this list is queried
 333          * in a round-robin manner from NRS core when obtaining a request
 334          * for handling. This ensures that requests from policies that at some
 335          * point transition away from the
 336          * ptlrpc_nrs_pol_state::NRS_POL_STATE_STARTED state are drained.
 337          */
 338         struct list_head                nrs_policy_queued;
 339         /**
 340          * Service partition for this NRS head
 341          */
 342         struct ptlrpc_service_part     *nrs_svcpt;
 343         /**
 344          * Primary policy, which is the preferred policy for handling RPCs
 345          */
 346         struct ptlrpc_nrs_policy       *nrs_policy_primary;
 347         /**
 348          * Fallback policy, which is the backup policy for handling RPCs
 349          */
 350         struct ptlrpc_nrs_policy       *nrs_policy_fallback;
 351         /**
 352          * This NRS head handles either HP or regular requests
 353          */
 354         enum ptlrpc_nrs_queue_type      nrs_queue_type;
 355         /**
 356          * # queued requests from all policies in this NRS head
 357          */
 358         unsigned long                   nrs_req_queued;
 359         /**
 360          * # scheduled requests from all policies in this NRS head
 361          */
 362         unsigned long                   nrs_req_started;
 363         /**
 364          * # policies on this NRS
 365          */
 366         unsigned                        nrs_num_pols;
 367         /**
 368          * This NRS head is in progress of starting a policy
 369          */
 370         unsigned                        nrs_policy_starting:1;
 371         /**
 372          * In progress of shutting down the whole NRS head; used during
 373          * unregistration
 374          */
 375         unsigned                        nrs_stopping:1;
 376         /**
 377          * NRS policy is throttling reqeust
 378          */
 379         unsigned                        nrs_throttling:1;
 380 };
 381
 382 #define NRS_POL_NAME_MAX                16
 383 #define NRS_POL_ARG_MAX                 16
 384
 385 struct ptlrpc_nrs_pol_desc;
 386
 387 /**
 388  * Service compatibility predicate; this determines whether a policy is adequate
 389  * for handling RPCs of a particular PTLRPC service.
 390  *
 391  * XXX:This should give the same result during policy registration and
 392  * unregistration, and for all partitions of a service; so the result should not
 393  * depend on temporal service or other properties, that may influence the
 394  * result.
 395  */
 396 typedef bool (*nrs_pol_desc_compat_t) (const struct ptlrpc_service *svc,
 397                                        const struct ptlrpc_nrs_pol_desc *desc);
 398
 399 struct ptlrpc_nrs_pol_conf {
 400         /**
 401          * Human-readable policy name
 402          */
 403         char                               nc_name[NRS_POL_NAME_MAX];
 404         /**
 405          * NRS operations for this policy
 406          */
 407         const struct ptlrpc_nrs_pol_ops   *nc_ops;
 408         /**
 409          * Service compatibility predicate
 410          */
 411         nrs_pol_desc_compat_t              nc_compat;
 412         /**
 413          * Set for policies that support a single ptlrpc service, i.e. ones that
 414          * have \a pd_compat set to nrs_policy_compat_one(). The variable value
 415          * depicts the name of the single service that such policies are
 416          * compatible with.
 417          */
 418         const char                        *nc_compat_svc_name;
 419         /**
 420          * Owner module for this policy descriptor; policies registering from a
 421          * different module to the one the NRS framework is held within
 422          * (currently ptlrpc), should set this field to THIS_MODULE.
 423          */
 424         struct module                     *nc_owner;
 425         /**
 426          * Policy registration flags; a bitmast of \e nrs_policy_flags
 427          */
 428         unsigned                           nc_flags;
 429 };
 430
 431 /**
 432  * NRS policy registering descriptor
 433  *
 434  * Is used to hold a description of a policy that can be passed to NRS core in
 435  * order to register the policy with NRS heads in different PTLRPC services.
 436  */
 437 struct ptlrpc_nrs_pol_desc {
 438         /**
 439          * Human-readable policy name
 440          */
 441         char                                    pd_name[NRS_POL_NAME_MAX];
 442         /**
 443          * Link into nrs_core::nrs_policies
 444          */
 445         struct list_head                        pd_list;
 446         /**
 447          * NRS operations for this policy
 448          */
 449         const struct ptlrpc_nrs_pol_ops        *pd_ops;
 450         /**
 451          * Service compatibility predicate
 452          */
 453         nrs_pol_desc_compat_t                   pd_compat;
 454         /**
 455          * Set for policies that are compatible with only one PTLRPC service.
 456          *
 457          * \see ptlrpc_nrs_pol_conf::nc_compat_svc_name
 458          */
 459         const char                             *pd_compat_svc_name;
 460         /**
 461          * Owner module for this policy descriptor.
 462          *
 463          * We need to hold a reference to the module whenever we might make use
 464          * of any of the module's contents, i.e.
 465          * - If one or more instances of the policy are at a state where they
 466          *   might be handling a request, i.e.
 467          *   ptlrpc_nrs_pol_state::NRS_POL_STATE_STARTED or
 468          *   ptlrpc_nrs_pol_state::NRS_POL_STATE_STOPPING as we will have to
 469          *   call into the policy's ptlrpc_nrs_pol_ops() handlers. A reference
 470          *   is taken on the module when
 471          *   \e ptlrpc_nrs_pol_desc::pd_refs becomes 1, and released when it
 472          *   becomes 0, so that we hold only one reference to the module maximum
 473          *   at any time.
 474          *
 475          *   We do not need to hold a reference to the module, even though we
 476          *   might use code and data from the module, in the following cases:
 477          * - During external policy registration, because this should happen in
 478          *   the module's init() function, in which case the module is safe from
 479          *   removal because a reference is being held on the module by the
 480          *   kernel, and iirc kmod (and I guess module-init-tools also) will
 481          *   serialize any racing processes properly anyway.
 482          * - During external policy unregistration, because this should happen
 483          *   in a module's exit() function, and any attempts to start a policy
 484          *   instance would need to take a reference on the module, and this is
 485          *   not possible once we have reached the point where the exit()
 486          *   handler is called.
 487          * - During service registration and unregistration, as service setup
 488          *   and cleanup, and policy registration, unregistration and policy
 489          *   instance starting, are serialized by \e nrs_core::nrs_mutex, so
 490          *   as long as users adhere to the convention of registering policies
 491          *   in init() and unregistering them in module exit() functions, there
 492          *   should not be a race between these operations.
 493          * - During any policy-specific lprocfs operations, because a reference
 494          *   is held by the kernel on a proc entry that has been entered by a
 495          *   syscall, so as long as proc entries are removed during
 496          *   unregistration time, then unregistration and lprocfs operations
 497          *   will be properly serialized.
 498          */
 499         struct module                          *pd_owner;
 500         /**
 501          * Bitmask of \e nrs_policy_flags
 502          */
 503         unsigned                                pd_flags;
 504         /**
 505          * # of references on this descriptor
 506          */
 507         atomic_t                                pd_refs;
 508 };
 509
 510 /**
 511  * NRS policy state
 512  *
 513  * Policies transition from one state to the other during their lifetime
 514  */
 515 enum ptlrpc_nrs_pol_state {
 516         /**
 517          * Not a valid policy state.
 518          */
 519         NRS_POL_STATE_INVALID,
 520         /**
 521          * Policies are at this state either at the start of their life, or
 522          * transition here when the user selects a different policy to act
 523          * as the primary one.
 524          */
 525         NRS_POL_STATE_STOPPED,
 526         /**
 527          * Policy is progress of stopping
 528          */
 529         NRS_POL_STATE_STOPPING,
 530         /**
 531          * Policy is in progress of starting
 532          */
 533         NRS_POL_STATE_STARTING,
 534         /**
 535          * A policy is in this state in two cases:
 536          * - it is the fallback policy, which is always in this state.
 537          * - it has been activated by the user; i.e. it is the primary policy,
 538          */
 539         NRS_POL_STATE_STARTED,
 540 };
 541
 542 /**
 543  * NRS policy information
 544  *
 545  * Used for obtaining information for the status of a policy via lprocfs
 546  */
 547 struct ptlrpc_nrs_pol_info {
 548         /**
 549          * Policy name
 550          */
 551         char                            pi_name[NRS_POL_NAME_MAX];
 552         /**
 553          * Policy argument
 554          */
 555         char                            pi_arg[NRS_POL_ARG_MAX];
 556         /**
 557          * Current policy state
 558          */
 559         enum ptlrpc_nrs_pol_state       pi_state;
 560         /**
 561          * # RPCs enqueued for later dispatching by the policy
 562          */
 563         long                            pi_req_queued;
 564         /**
 565          * # RPCs started for dispatch by the policy
 566          */
 567         long                            pi_req_started;
 568         /**
 569          * Is this a fallback policy?
 570          */
 571         unsigned                        pi_fallback:1;
 572 };
 573
 574 /**
 575  * NRS policy
 576  *
 577  * There is one instance of this for each policy in each NRS head of each
 578  * PTLRPC service partition.
 579  */
 580 struct ptlrpc_nrs_policy {
 581         /**
 582          * Linkage into the NRS head's list of policies,
 583          * ptlrpc_nrs:nrs_policy_list
 584          */
 585         struct list_head                pol_list;
 586         /**
 587          * Linkage into the NRS head's list of policies with enqueued
 588          * requests ptlrpc_nrs:nrs_policy_queued
 589          */
 590         struct list_head                pol_list_queued;
 591         /**
 592          * Current state of this policy
 593          */
 594         enum ptlrpc_nrs_pol_state       pol_state;
 595         /**
 596          * Bitmask of nrs_policy_flags
 597          */
 598         unsigned                        pol_flags;
 599         /**
 600          * # RPCs enqueued for later dispatching by the policy
 601          */
 602         long                            pol_req_queued;
 603         /**
 604          * # RPCs started for dispatch by the policy
 605          */
 606         long                            pol_req_started;
 607         /**
 608          * Usage Reference count taken on the policy instance
 609          */
 610         long                            pol_ref;
 611         /**
 612          * Human-readable policy argument
 613          */
 614         char                            pol_arg[NRS_POL_ARG_MAX];
 615         /**
 616          * The NRS head this policy has been created at
 617          */
 618         struct ptlrpc_nrs              *pol_nrs;
 619         /**
 620          * Private policy data; varies by policy type
 621          */
 622         void                           *pol_private;
 623         /**
 624          * Policy descriptor for this policy instance.
 625          */
 626         struct ptlrpc_nrs_pol_desc     *pol_desc;
 627 };
 628
 629 /**
 630  * NRS resource
 631  *
 632  * Resources are embedded into two types of NRS entities:
 633  * - Inside NRS policies, in the policy's private data in
 634  *   ptlrpc_nrs_policy::pol_private
 635  * - In objects that act as prime-level scheduling entities in different NRS
 636  *   policies; e.g. on a policy that performs round robin or similar order
 637  *   scheduling across client NIDs, there would be one NRS resource per unique
 638  *   client NID. On a policy which performs round robin scheduling across
 639  *   backend filesystem objects, there would be one resource associated with
 640  *   each of the backend filesystem objects partaking in the scheduling
 641  *   performed by the policy.
 642  *
 643  * NRS resources share a parent-child relationship, in which resources embedded
 644  * in policy instances are the parent entities, with all scheduling entities
 645  * a policy schedules across being the children, thus forming a simple resource
 646  * hierarchy. This hierarchy may be extended with one or more levels in the
 647  * future if the ability to have more than one primary policy is added.
 648  *
 649  * Upon request initialization, references to the then active NRS policies are
 650  * taken and used to later handle the dispatching of the request with one of
 651  * these policies.
 652  *
 653  * \see nrs_resource_get_safe()
 654  * \see ptlrpc_nrs_req_add()
 655  */
 656 struct ptlrpc_nrs_resource {
 657         /**
 658          * This NRS resource's parent; is NULL for resources embedded in NRS
 659          * policy instances; i.e. those are top-level ones.
 660          */
 661         struct ptlrpc_nrs_resource     *res_parent;
 662         /**
 663          * The policy associated with this resource.
 664          */
 665         struct ptlrpc_nrs_policy       *res_policy;
 666 };
 667
 668 enum {
 669         NRS_RES_FALLBACK,
 670         NRS_RES_PRIMARY,
 671         NRS_RES_MAX
 672 };
 673
 674 #include <lustre_nrs_fifo.h>
 675 #include <lustre_nrs_tbf.h>
 676 #include <lustre_nrs_crr.h>
 677 #include <lustre_nrs_orr.h>
 678 #include <lustre_nrs_delay.h>
 679
 680 /**
 681  * NRS request
 682  *
 683  * Instances of this object exist embedded within ptlrpc_request; the main
 684  * purpose of this object is to hold references to the request's resources
 685  * for the lifetime of the request, and to hold properties that policies use
 686  * use for determining the request's scheduling priority.
 687  * */
 688 struct ptlrpc_nrs_request {
 689         /**
 690          * The request's resource hierarchy.
 691          */
 692         struct ptlrpc_nrs_resource     *nr_res_ptrs[NRS_RES_MAX];
 693         /**
 694          * Index into ptlrpc_nrs_request::nr_res_ptrs of the resource of the
 695          * policy that was used to enqueue the request.
 696          *
 697          * \see nrs_request_enqueue()
 698          */
 699         unsigned                        nr_res_idx;
 700         unsigned                        nr_initialized:1;
 701         unsigned                        nr_enqueued:1;
 702         unsigned                        nr_started:1;
 703         unsigned                        nr_finalized:1;
 704         struct cfs_binheap_node         nr_node;
 705
 706         /**
 707          * Policy-specific fields, used for determining a request's scheduling
 708          * priority, and other supporting functionality.
 709          */
 710         union {
 711                 /**
 712                  * Fields for the FIFO policy
 713                  */
 714                 struct nrs_fifo_req     fifo;
 715                 /**
 716                  * CRR-N request defintion
 717                  */
 718                 struct nrs_crrn_req     crr;
 719                 /** ORR and TRR share the same request definition */
 720                 struct nrs_orr_req      orr;
 721                 /**
 722                  * TBF request definition
 723                  */
 724                 struct nrs_tbf_req      tbf;
 725                 /**
 726                  * Fields for the delay policy
 727                  */
 728                 struct nrs_delay_req    delay;
 729         } nr_u;
 730         /**
 731          * Externally-registering policies may want to use this to allocate
 732          * their own request properties.
 733          */
 734         void                           *ext;
 735 };
 736
 737 /** @} nrs */
 738 #endif