lustre/include/lu_object.h

   1 /* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
   2  * vim:expandtab:shiftwidth=8:tabstop=8:
   3  *
   4  *  Copyright (C) 2006 Cluster File Systems, Inc.
   5  *
   6  *   This file is part of Lustre, http://www.lustre.org.
   7  *
   8  *   Lustre is free software; you can redistribute it and/or
   9  *   modify it under the terms of version 2 of the GNU General Public
  10  *   License as published by the Free Software Foundation.
  11  *
  12  *   Lustre is distributed in the hope that it will be useful,
  13  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *   GNU General Public License for more details.
  16  *
  17  *   You should have received a copy of the GNU General Public License
  18  *   along with Lustre; if not, write to the Free Software
  19  *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  20  *
  21  */
  22
  23 #ifndef __LUSTRE_LU_OBJECT_H
  24 #define __LUSTRE_LU_OBJECT_H
  25
  26 /*
  27  * struct lu_fid
  28  */
  29 #include <lustre/lustre_idl.h>
  30
  31 #include <libcfs/list.h>
  32 #include <libcfs/kp30.h>
  33
  34 /*
  35  * Layered objects support for CMD3/C5.
  36  */
  37
  38 struct seq_file;
  39 struct proc_dir_entry;
  40 struct lustre_cfg;
  41 struct lprocfs_stats;
  42
  43 /*
  44  * lu_* data-types represent server-side entities shared by data and meta-data
  45  * stacks.
  46  *
  47  * Design goals:
  48  *
  49  * 0. support for layering.
  50  *
  51  *     Server side object is split into layers, one per device in the
  52  *     corresponding device stack. Individual layer is represented by struct
  53  *     lu_object. Compound layered object --- by struct lu_object_header. Most
  54  *     interface functions take lu_object as an argument and operate on the
  55  *     whole compound object. This decision was made due to the following
  56  *     reasons:
  57  *
  58  *        - it's envisaged that lu_object will be used much more often than
  59  *        lu_object_header;
  60  *
  61  *        - we want lower (non-top) layers to be able to initiate operations
  62  *        on the whole object.
  63  *
  64  *     Generic code supports layering more complex than simple stacking, e.g.,
  65  *     it is possible that at some layer object "spawns" multiple sub-objects
  66  *     on the lower layer.
  67  *
  68  * 1. fid-based identification.
  69  *
  70  *     Compound object is uniquely identified by its fid. Objects are indexed
  71  *     by their fids (hash table is used for index).
  72  *
  73  * 2. caching and life-cycle management.
  74  *
  75  *     Object's life-time is controlled by reference counting. When reference
  76  *     count drops to 0, object is returned to cache. Cached objects still
  77  *     retain their identity (i.e., fid), and can be recovered from cache.
  78  *
  79  *     Objects are kept in the global LRU list, and lu_site_purge() function
  80  *     can be used to reclaim given number of unused objects from the tail of
  81  *     the LRU.
  82  *
  83  * 3. avoiding recursion.
  84  *
  85  *     Generic code tries to replace recursion through layers by iterations
  86  *     where possible. Additionally to the end of reducing stack consumption,
  87  *     data, when practically possible, are allocated through lu_context_key
  88  *     interface rather than on stack.
  89  *
  90  */
  91
  92 struct lu_site;
  93 struct lu_object;
  94 struct lu_device;
  95 struct lu_object_header;
  96 struct lu_context;
  97 struct lu_env;
  98
  99 /*
 100  * Operations common for data and meta-data devices.
 101  */
 102 struct lu_device_operations {
 103         /*
 104          * Object creation protocol.
 105          *
 106          * Due to design goal of avoiding recursion, object creation (see
 107          * lu_object_alloc()) is somewhat involved:
 108          *
 109          *  - first, ->ldo_object_alloc() method of the top-level device
 110          *  in the stack is called. It should allocate top level object
 111          *  (including lu_object_header), but without any lower-layer
 112          *  sub-object(s).
 113          *
 114          *  - then lu_object_alloc() sets fid in the header of newly created
 115          *  object.
 116          *
 117          *  - then ->loo_object_init() (a method from struct
 118          *  lu_object_operations) is called. It has to allocate lower-layer
 119          *  object(s). To do this, ->loo_object_init() calls
 120          *  ldo_object_alloc() of the lower-layer device(s).
 121          *
 122          *  - for all new objects allocated by ->loo_object_init() (and
 123          *  inserted into object stack), ->loo_object_init() is called again
 124          *  repeatedly, until no new objects are created.
 125          *
 126          */
 127
 128         /*
 129          * Allocate object for the given device (without lower-layer
 130          * parts). This is called by ->loo_object_init() from the parent
 131          * layer, and should setup at least ->lo_dev and ->lo_ops fields of
 132          * resulting lu_object.
 133          *
 134          * postcondition: ergo(!IS_ERR(result), result->lo_dev ==  d &&
 135          *                                      result->lo_ops != NULL);
 136          */
 137         struct lu_object *(*ldo_object_alloc)(const struct lu_env *env,
 138                                               const struct lu_object_header *h,
 139                                               struct lu_device *d);
 140         /*
 141          * process config specific for device
 142          */
 143         int (*ldo_process_config)(const struct lu_env *env,
 144                                   struct lu_device *, struct lustre_cfg *);
 145         int (*ldo_recovery_complete)(const struct lu_env *,
 146                                      struct lu_device *);
 147
 148 };
 149
 150 /*
 151  * Type of "printer" function used by ->loo_object_print() method.
 152  *
 153  * Printer function is needed to provide some flexibility in (semi-)debugging
 154  * output: possible implementations: printk, CDEBUG, sysfs/seq_file
 155  */
 156 typedef int (*lu_printer_t)(const struct lu_env *env,
 157                             void *cookie, const char *format, ...)
 158         __attribute__ ((format (printf, 3, 4)));
 159
 160 /*
 161  * Operations specific for particular lu_object.
 162  */
 163 struct lu_object_operations {
 164
 165         /*
 166          * Allocate lower-layer parts of the object by calling
 167          * ->ldo_object_alloc() of the corresponding underlying device.
 168          *
 169          * This method is called once for each object inserted into object
 170          * stack. It's responsibility of this method to insert lower-layer
 171          * object(s) it create into appropriate places of object stack.
 172          */
 173         int (*loo_object_init)(const struct lu_env *env,
 174                                struct lu_object *o);
 175         /*
 176          * Called (in top-to-bottom order) during object allocation after all
 177          * layers were allocated and initialized. Can be used to perform
 178          * initialization depending on lower layers.
 179          */
 180         int (*loo_object_start)(const struct lu_env *env,
 181                                 struct lu_object *o);
 182         /*
 183          * Called before ->loo_object_free() to signal that object is being
 184          * destroyed. Dual to ->loo_object_init().
 185          */
 186         void (*loo_object_delete)(const struct lu_env *env,
 187                                   struct lu_object *o);
 188
 189         /*
 190          * Dual to ->ldo_object_alloc(). Called when object is removed from
 191          * memory.
 192          */
 193         void (*loo_object_free)(const struct lu_env *env,
 194                                 struct lu_object *o);
 195
 196         /*
 197          * Called when last active reference to the object is released (and
 198          * object returns to the cache). This method is optional.
 199          */
 200         void (*loo_object_release)(const struct lu_env *env,
 201                                    struct lu_object *o);
 202         /*
 203          * Debugging helper. Print given object.
 204          */
 205         int (*loo_object_print)(const struct lu_env *env, void *cookie,
 206                                 lu_printer_t p, const struct lu_object *o);
 207         /*
 208          * Optional debugging method. Returns true iff method is internally
 209          * consistent.
 210          */
 211         int (*loo_object_invariant)(const struct lu_object *o);
 212 };
 213
 214 /*
 215  * Type of lu_device.
 216  */
 217 struct lu_device_type;
 218
 219 /*
 220  * Device: a layer in the server side abstraction stacking.
 221  */
 222 struct lu_device {
 223         /*
 224          * reference count. This is incremented, in particular, on each object
 225          * created at this layer.
 226          *
 227          * XXX which means that atomic_t is probably too small.
 228          */
 229         atomic_t                     ld_ref;
 230         /*
 231          * Pointer to device type. Never modified once set.
 232          */
 233         struct lu_device_type       *ld_type;
 234         /*
 235          * Operation vector for this device.
 236          */
 237         struct lu_device_operations *ld_ops;
 238         /*
 239          * Stack this device belongs to.
 240          */
 241         struct lu_site              *ld_site;
 242         struct proc_dir_entry       *ld_proc_entry;
 243
 244         /* XXX: temporary back pointer into obd. */
 245         struct obd_device           *ld_obd;
 246 };
 247
 248 struct lu_device_type_operations;
 249
 250 /*
 251  * Tag bits for device type. They are used to distinguish certain groups of
 252  * device types.
 253  */
 254 enum lu_device_tag {
 255         /* this is meta-data device */
 256         LU_DEVICE_MD = (1 << 0),
 257         /* this is data device */
 258         LU_DEVICE_DT = (1 << 1)
 259 };
 260
 261 /*
 262  * Type of device.
 263  */
 264 struct lu_device_type {
 265         /*
 266          * Tag bits. Taken from enum lu_device_tag. Never modified once set.
 267          */
 268         __u32                             ldt_tags;
 269         /*
 270          * Name of this class. Unique system-wide. Never modified once set.
 271          */
 272         char                             *ldt_name;
 273         /*
 274          * Operations for this type.
 275          */
 276         struct lu_device_type_operations *ldt_ops;
 277         /*
 278          * XXX: temporary pointer to associated obd_type.
 279          */
 280         struct obd_type                  *ldt_obd_type;
 281         /*
 282          * XXX: temporary: context tags used by obd_*() calls.
 283          */
 284         __u32                             ldt_ctx_tags;
 285 };
 286
 287 /*
 288  * Operations on a device type.
 289  */
 290 struct lu_device_type_operations {
 291         /*
 292          * Allocate new device.
 293          */
 294         struct lu_device *(*ldto_device_alloc)(const struct lu_env *env,
 295                                                struct lu_device_type *t,
 296                                                struct lustre_cfg *lcfg);
 297         /*
 298          * Free device. Dual to ->ldto_device_alloc().
 299          */
 300         void (*ldto_device_free)(const struct lu_env *,
 301                                  struct lu_device *);
 302
 303         /*
 304          * Initialize the devices after allocation
 305          */
 306         int  (*ldto_device_init)(const struct lu_env *env,
 307                                  struct lu_device *, const char *,
 308                                  struct lu_device *);
 309         /*
 310          * Finalize device. Dual to ->ldto_device_init(). Returns pointer to
 311          * the next device in the stack.
 312          */
 313         struct lu_device *(*ldto_device_fini)(const struct lu_env *env,
 314                                               struct lu_device *);
 315
 316         /*
 317          * Initialize device type. This is called on module load.
 318          */
 319         int  (*ldto_init)(struct lu_device_type *t);
 320         /*
 321          * Finalize device type. Dual to ->ldto_init(). Called on module
 322          * unload.
 323          */
 324         void (*ldto_fini)(struct lu_device_type *t);
 325 };
 326
 327 /*
 328  * Flags for the object layers.
 329  */
 330 enum lu_object_flags {
 331         /*
 332          * this flags is set if ->loo_object_init() has been called for this
 333          * layer. Used by lu_object_alloc().
 334          */
 335         LU_OBJECT_ALLOCATED = (1 << 0)
 336 };
 337
 338 /*
 339  * Common object attributes.
 340  */
 341 /* valid flags */
 342 enum la_valid {
 343         LA_ATIME = 1 << 0,
 344         LA_MTIME = 1 << 1,
 345         LA_CTIME = 1 << 2,
 346         LA_SIZE  = 1 << 3,
 347         LA_MODE  = 1 << 4,
 348         LA_UID   = 1 << 5,
 349         LA_GID   = 1 << 6,
 350         LA_BLOCKS = 1 << 7,
 351         LA_TYPE   = 1 << 8,
 352         LA_FLAGS  = 1 << 9,
 353         LA_NLINK  = 1 << 10,
 354         LA_RDEV   = 1 << 11,
 355         LA_BLKSIZE = 1 << 12,
 356 };
 357
 358 struct lu_attr {
 359         __u64          la_size;   /* size in bytes */
 360         __u64          la_mtime;  /* modification time in seconds since Epoch */
 361         __u64          la_atime;  /* access time in seconds since Epoch */
 362         __u64          la_ctime;  /* change time in seconds since Epoch */
 363         __u64          la_blocks; /* 512-byte blocks allocated to object */
 364         __u32          la_mode;   /* permission bits and file type */
 365         __u32          la_uid;    /* owner id */
 366         __u32          la_gid;    /* group id */
 367         __u32          la_flags;  /* object flags */
 368         __u32          la_nlink;  /* number of persistent references to this
 369                                    * object */
 370         __u32          la_blksize; /* blk size of the object*/
 371
 372         __u32          la_rdev;   /* real device */
 373         __u64          la_valid;  /* valid bits */
 374 };
 375
 376
 377 /*
 378  * Layer in the layered object.
 379  */
 380 struct lu_object {
 381         /*
 382          * Header for this object.
 383          */
 384         struct lu_object_header     *lo_header;
 385         /*
 386          * Device for this layer.
 387          */
 388         struct lu_device            *lo_dev;
 389         /*
 390          * Operations for this object.
 391          */
 392         struct lu_object_operations *lo_ops;
 393         /*
 394          * Linkage into list of all layers.
 395          */
 396         struct list_head             lo_linkage;
 397         /*
 398          * Depth. Top level layer depth is 0.
 399          */
 400         int                          lo_depth;
 401         /*
 402          * Flags from enum lu_object_flags.
 403          */
 404         unsigned long                lo_flags;
 405 };
 406
 407 enum lu_object_header_flags {
 408         /*
 409          * Don't keep this object in cache. Object will be destroyed as soon
 410          * as last reference to it is released. This flag cannot be cleared
 411          * once set.
 412          */
 413         LU_OBJECT_HEARD_BANSHEE = 0
 414 };
 415
 416 enum lu_object_header_attr {
 417         LOHA_EXISTS   = 1 << 0,
 418         LOHA_REMOTE   = 1 << 1,
 419         /*
 420          * UNIX file type is stored in S_IFMT bits.
 421          */
 422         LOHA_FT_START = 1 << 12, /* S_IFIFO */
 423         LOHA_FT_END   = 1 << 15, /* S_IFREG */
 424 };
 425
 426 /*
 427  * "Compound" object, consisting of multiple layers.
 428  *
 429  * Compound object with given fid is unique with given lu_site.
 430  *
 431  * Note, that object does *not* necessary correspond to the real object in the
 432  * persistent storage: object is an anchor for locking and method calling, so
 433  * it is created for things like not-yet-existing child created by mkdir or
 434  * create calls. ->loo_exists() can be used to check whether object is backed
 435  * by persistent storage entity.
 436  */
 437 struct lu_object_header {
 438         /*
 439          * Object flags from enum lu_object_header_flags. Set and checked
 440          * atomically.
 441          */
 442         unsigned long     loh_flags;
 443         /*
 444          * Object reference count. Protected by site guard lock.
 445          */
 446         atomic_t          loh_ref;
 447         /*
 448          * Fid, uniquely identifying this object.
 449          */
 450         struct lu_fid     loh_fid;
 451         /*
 452          * Common object attributes, cached for efficiency. From enum
 453          * lu_object_header_attr.
 454          */
 455         __u32             loh_attr;
 456         /*
 457          * Linkage into per-site hash table. Protected by site guard lock.
 458          */
 459         struct hlist_node loh_hash;
 460         /*
 461          * Linkage into per-site LRU list. Protected by site guard lock.
 462          */
 463         struct list_head  loh_lru;
 464         /*
 465          * Linkage into list of layers. Never modified once set (except lately
 466          * during object destruction). No locking is necessary.
 467          */
 468         struct list_head  loh_layers;
 469 };
 470
 471 struct fld;
 472
 473 /*
 474  * lu_site is a "compartment" within which objects are unique, and LRU
 475  * discipline is maintained.
 476  *
 477  * lu_site exists so that multiple layered stacks can co-exist in the same
 478  * address space.
 479  *
 480  * lu_site has the same relation to lu_device as lu_object_header to
 481  * lu_object.
 482  */
 483 struct lu_site {
 484         /*
 485          * lock protecting:
 486          *
 487          *        - ->ls_hash hash table (and its linkages in objects);
 488          *
 489          *        - ->ls_lru list (and its linkages in objects);
 490          *
 491          *        - 0/1 transitions of object ->loh_ref reference count;
 492          *
 493          * yes, it's heavy.
 494          */
 495         rwlock_t              ls_guard;
 496         /*
 497          * Hash-table where objects are indexed by fid.
 498          */
 499         struct hlist_head    *ls_hash;
 500         /*
 501          * Bit-mask for hash-table size.
 502          */
 503         int                   ls_hash_mask;
 504         /*
 505          * Order of hash-table.
 506          */
 507         int                   ls_hash_bits;
 508         /*
 509          * Number of buckets in the hash-table.
 510          */
 511         int                   ls_hash_size;
 512
 513         /*
 514          * LRU list, updated on each access to object. Protected by
 515          * ->ls_guard.
 516          *
 517          * "Cold" end of LRU is ->ls_lru.next. Accessed object are moved to
 518          * the ->ls_lru.prev (this is due to the non-existence of
 519          * list_for_each_entry_safe_reverse()).
 520          */
 521         struct list_head      ls_lru;
 522         /*
 523          * Total number of objects in this site. Protected by ->ls_guard.
 524          */
 525         unsigned              ls_total;
 526         /*
 527          * Total number of objects in this site with reference counter greater
 528          * than 0. Protected by ->ls_guard.
 529          */
 530         unsigned              ls_busy;
 531
 532         /*
 533          * Top-level device for this stack.
 534          */
 535         struct lu_device     *ls_top_dev;
 536         /*
 537          * mds number of this site.
 538          */
 539         mdsno_t               ls_node_id;
 540         /*
 541          * Fid location database
 542          */
 543         struct lu_server_fld *ls_server_fld;
 544         struct lu_client_fld *ls_client_fld;
 545
 546         /*
 547          * Server Seq Manager
 548          */
 549         struct lu_server_seq *ls_server_seq;
 550
 551         /*
 552          * Controller Seq Manager
 553          */
 554         struct lu_server_seq *ls_control_seq;
 555         struct obd_export    *ls_control_exp;
 556
 557         /*
 558          * Client Seq Manager
 559          */
 560         struct lu_client_seq *ls_client_seq;
 561
 562         /* statistical counters. Protected by nothing, races are accepted. */
 563         struct {
 564                 __u32 s_created;
 565                 __u32 s_cache_hit;
 566                 __u32 s_cache_miss;
 567                 /*
 568                  * Number of hash-table entry checks made.
 569                  *
 570                  *       ->s_cache_check / (->s_cache_miss + ->s_cache_hit)
 571                  *
 572                  * is an average number of hash slots inspected during single
 573                  * lookup.
 574                  */
 575                 __u32 s_cache_check;
 576                 /* raced cache insertions */
 577                 __u32 s_cache_race;
 578                 __u32 s_lru_purged;
 579         } ls_stats;
 580
 581         /*
 582          * Linkage into global list of sites.
 583          */
 584         struct list_head      ls_linkage;
 585         struct lprocfs_stats *ls_time_stats;
 586 };
 587
 588 /*
 589  * Constructors/destructors.
 590  */
 591
 592 /*
 593  * Initialize site @s, with @d as the top level device.
 594  */
 595 int  lu_site_init(struct lu_site *s, struct lu_device *d);
 596 /*
 597  * Finalize @s and release its resources.
 598  */
 599 void lu_site_fini(struct lu_site *s);
 600
 601 /*
 602  * Called when initialization of stack for this site is completed.
 603  */
 604 int lu_site_init_finish(struct lu_site *s);
 605
 606 /*
 607  * Acquire additional reference on device @d
 608  */
 609 void lu_device_get(struct lu_device *d);
 610 /*
 611  * Release reference on device @d.
 612  */
 613 void lu_device_put(struct lu_device *d);
 614
 615 /*
 616  * Initialize device @d of type @t.
 617  */
 618 int lu_device_init(struct lu_device *d, struct lu_device_type *t);
 619 /*
 620  * Finalize device @d.
 621  */
 622 void lu_device_fini(struct lu_device *d);
 623
 624 /*
 625  * Initialize compound object.
 626  */
 627 int lu_object_header_init(struct lu_object_header *h);
 628 /*
 629  * Finalize compound object.
 630  */
 631 void lu_object_header_fini(struct lu_object_header *h);
 632
 633 /*
 634  * Initialize object @o that is part of compound object @h and was created by
 635  * device @d.
 636  */
 637 int lu_object_init(struct lu_object *o,
 638                    struct lu_object_header *h, struct lu_device *d);
 639 /*
 640  * Finalize object and release its resources.
 641  */
 642 void lu_object_fini(struct lu_object *o);
 643 /*
 644  * Add object @o as first layer of compound object @h.
 645  *
 646  * This is typically called by the ->ldo_object_alloc() method of top-level
 647  * device.
 648  */
 649 void lu_object_add_top(struct lu_object_header *h, struct lu_object *o);
 650 /*
 651  * Add object @o as a layer of compound object, going after @before.1
 652  *
 653  * This is typically called by the ->ldo_object_alloc() method of
 654  * @before->lo_dev.
 655  */
 656 void lu_object_add(struct lu_object *before, struct lu_object *o);
 657
 658 /*
 659  * Caching and reference counting.
 660  */
 661
 662 /*
 663  * Acquire additional reference to the given object. This function is used to
 664  * attain additional reference. To acquire initial reference use
 665  * lu_object_find().
 666  */
 667 static inline void lu_object_get(struct lu_object *o)
 668 {
 669         LASSERT(atomic_read(&o->lo_header->loh_ref) > 0);
 670         atomic_inc(&o->lo_header->loh_ref);
 671 }
 672
 673 /*
 674  * Return true of object will not be cached after last reference to it is
 675  * released.
 676  */
 677 static inline int lu_object_is_dying(const struct lu_object_header *h)
 678 {
 679         return test_bit(LU_OBJECT_HEARD_BANSHEE, &h->loh_flags);
 680 }
 681
 682 /*
 683  * Decrease reference counter on object. If last reference is freed, return
 684  * object to the cache, unless lu_object_is_dying(o) holds. In the latter
 685  * case, free object immediately.
 686  */
 687 void lu_object_put(const struct lu_env *env,
 688                    struct lu_object *o);
 689
 690 /*
 691  * Free @nr objects from the cold end of the site LRU list.
 692  */
 693 int lu_site_purge(const struct lu_env *env, struct lu_site *s, int nr);
 694
 695 /*
 696  * Print all objects in @s.
 697  */
 698 void lu_site_print(const struct lu_env *env, struct lu_site *s, void *cookie,
 699                    lu_printer_t printer);
 700 /*
 701  * Search cache for an object with the fid @f. If such object is found, return
 702  * it. Otherwise, create new object, insert it into cache and return it. In
 703  * any case, additional reference is acquired on the returned object.
 704  */
 705 struct lu_object *lu_object_find(const struct lu_env *env,
 706                                  struct lu_site *s, const struct lu_fid *f);
 707
 708 /*
 709  * Helpers.
 710  */
 711
 712 /*
 713  * First (topmost) sub-object of given compound object
 714  */
 715 static inline struct lu_object *lu_object_top(struct lu_object_header *h)
 716 {
 717         LASSERT(!list_empty(&h->loh_layers));
 718         return container_of0(h->loh_layers.next, struct lu_object, lo_linkage);
 719 }
 720
 721 /*
 722  * Next sub-object in the layering
 723  */
 724 static inline struct lu_object *lu_object_next(const struct lu_object *o)
 725 {
 726         return container_of0(o->lo_linkage.next, struct lu_object, lo_linkage);
 727 }
 728
 729 /*
 730  * Pointer to the fid of this object.
 731  */
 732 static inline const struct lu_fid *lu_object_fid(const struct lu_object *o)
 733 {
 734         return &o->lo_header->loh_fid;
 735 }
 736
 737 /*
 738  * return device operations vector for this object
 739  */
 740 static inline struct lu_device_operations *
 741 lu_object_ops(const struct lu_object *o)
 742 {
 743         return o->lo_dev->ld_ops;
 744 }
 745
 746 /*
 747  * Given a compound object, find its slice, corresponding to the device type
 748  * @dtype.
 749  */
 750 struct lu_object *lu_object_locate(struct lu_object_header *h,
 751                                    struct lu_device_type *dtype);
 752
 753 struct lu_cdebug_print_info {
 754         int         lpi_subsys;
 755         int         lpi_mask;
 756         const char *lpi_file;
 757         const char *lpi_fn;
 758         int         lpi_line;
 759 };
 760
 761 /*
 762  * Printer function emitting messages through libcfs_debug_msg().
 763  */
 764 int lu_cdebug_printer(const struct lu_env *env,
 765                       void *cookie, const char *format, ...);
 766
 767 #define DECLARE_LU_CDEBUG_PRINT_INFO(var, mask) \
 768         struct lu_cdebug_print_info var = {     \
 769                 .lpi_subsys = DEBUG_SUBSYSTEM,  \
 770                 .lpi_mask   = (mask),           \
 771                 .lpi_file   = __FILE__,         \
 772                 .lpi_fn     = __FUNCTION__,     \
 773                 .lpi_line   = __LINE__          \
 774         };
 775
 776 /*
 777  * Print object description followed by user-supplied message.
 778  */
 779 #define LU_OBJECT_DEBUG(mask, env, object, format, ...)                 \
 780 ({                                                                      \
 781         static DECLARE_LU_CDEBUG_PRINT_INFO(__info, mask);              \
 782                                                                         \
 783         lu_object_print(env, &__info, lu_cdebug_printer, object);       \
 784         CDEBUG(mask, format , ## __VA_ARGS__);                          \
 785 })
 786
 787 /*
 788  * Print human readable representation of the @o to the @f.
 789  */
 790 void lu_object_print(const struct lu_env *env, void *cookie,
 791                      lu_printer_t printer, const struct lu_object *o);
 792
 793 /*
 794  * Check object consistency.
 795  */
 796 int lu_object_invariant(const struct lu_object *o);
 797
 798 /*
 799  * Returns 1 iff object @o exists on the stable storage,
 800  * returns -1 iff object @o is on remote server.
 801  */
 802 static inline int lu_object_exists(const struct lu_object *o)
 803 {
 804         __u32 attr;
 805
 806         attr = o->lo_header->loh_attr;
 807         if (attr & LOHA_REMOTE)
 808                 return -1;
 809         else if (attr & LOHA_EXISTS)
 810                 return +1;
 811         else
 812                 return 0;
 813 }
 814
 815 static inline int lu_object_assert_exists(const struct lu_object *o)
 816 {
 817         return lu_object_exists(o) != 0;
 818 }
 819
 820 static inline int lu_object_assert_not_exists(const struct lu_object *o)
 821 {
 822         return lu_object_exists(o) <= 0;
 823 }
 824
 825 /*
 826  * Attr of this object.
 827  */
 828 static inline const __u32 lu_object_attr(const struct lu_object *o)
 829 {
 830         LASSERT(lu_object_exists(o) > 0);
 831         return o->lo_header->loh_attr;
 832 }
 833
 834 struct lu_rdpg {
 835         /* input params, should be filled out by mdt */
 836         __u32                   rp_hash;        /* hash */
 837         int                     rp_count;       /* count in bytes       */
 838         int                     rp_npages;      /* number of pages      */
 839         struct page           **rp_pages;       /* pointers to pages    */
 840 };
 841
 842 enum lu_xattr_flags {
 843         LU_XATTR_REPLACE = (1 << 0),
 844         LU_XATTR_CREATE  = (1 << 1)
 845 };
 846
 847 /*
 848  * lu_context. Execution context for lu_object methods. Currently associated
 849  * with thread.
 850  *
 851  * All lu_object methods, except device and device type methods (called during
 852  * system initialization and shutdown) are executed "within" some
 853  * lu_context. This means, that pointer to some "current" lu_context is passed
 854  * as an argument to all methods.
 855  *
 856  * All service ptlrpc threads create lu_context as part of their
 857  * initialization. It is possible to create "stand-alone" context for other
 858  * execution environments (like system calls).
 859  *
 860  * lu_object methods mainly use lu_context through lu_context_key interface
 861  * that allows each layer to associate arbitrary pieces of data with each
 862  * context (see pthread_key_create(3) for similar interface).
 863  *
 864  */
 865 struct lu_context {
 866         /*
 867          * Theoretically we'd want to use lu_objects and lu_contexts on the
 868          * client side too. On the other hand, we don't want to allocate
 869          * values of server-side keys for the client contexts and vice versa.
 870          *
 871          * To achieve this, set of tags in introduced. Contexts and keys are
 872          * marked with tags. Key value are created only for context whose set
 873          * of tags has non-empty intersection with one for key. Tags are taken
 874          * from enum lu_context_tag.
 875          */
 876         __u32                  lc_tags;
 877         /*
 878          * Pointer to the home service thread. NULL for other execution
 879          * contexts.
 880          */
 881         struct ptlrpc_thread  *lc_thread;
 882         /*
 883          * Pointer to an array with key values. Internal implementation
 884          * detail.
 885          */
 886         void                 **lc_value;
 887 };
 888
 889 /*
 890  * lu_context_key interface. Similar to pthread_key.
 891  */
 892
 893 enum lu_context_tag {
 894         /*
 895          * Thread on md server
 896          */
 897         LCT_MD_THREAD = 1 << 0,
 898         /*
 899          * Thread on dt server
 900          */
 901         LCT_DT_THREAD = 1 << 1,
 902         /*
 903          * Context for transaction handle
 904          */
 905         LCT_TX_HANDLE = 1 << 2,
 906         /*
 907          * Thread on client
 908          */
 909         LCT_CL_THREAD = 1 << 3,
 910         /*
 911          * Per-request session on server
 912          */
 913         LCT_SESSION   = 1 << 4,
 914         /*
 915          * Don't add references for modules creating key values in that context.
 916          * This is only for contexts used internally by lu_object framework.
 917          */
 918         LCT_NOREF     = 1 << 30,
 919         /*
 920          * Contexts usable in cache shrinker thread.
 921          */
 922         LCT_SHRINKER  = LCT_MD_THREAD|LCT_DT_THREAD|LCT_CL_THREAD|LCT_NOREF
 923 };
 924
 925 /*
 926  * Key. Represents per-context value slot.
 927  */
 928 struct lu_context_key {
 929         /*
 930          * Set of tags for which values of this key are to be instantiated.
 931          */
 932         __u32 lct_tags;
 933         /*
 934          * Value constructor. This is called when new value is created for a
 935          * context. Returns pointer to new value of error pointer.
 936          */
 937         void  *(*lct_init)(const struct lu_context *ctx,
 938                            struct lu_context_key *key);
 939         /*
 940          * Value destructor. Called when context with previously allocated
 941          * value of this slot is destroyed. @data is a value that was returned
 942          * by a matching call to ->lct_init().
 943          */
 944         void   (*lct_fini)(const struct lu_context *ctx,
 945                            struct lu_context_key *key, void *data);
 946         /*
 947          * Optional method called on lu_context_exit() for all allocated
 948          * keys. Can be used by debugging code checking that locks are
 949          * released, etc.
 950          */
 951         void   (*lct_exit)(const struct lu_context *ctx,
 952                            struct lu_context_key *key, void *data);
 953         /*
 954          * Internal implementation detail: index within ->lc_value[] reserved
 955          * for this key.
 956          */
 957         int      lct_index;
 958         /*
 959          * Internal implementation detail: number of values created for this
 960          * key.
 961          */
 962         atomic_t lct_used;
 963         /*
 964          * Internal implementation detail: module for this key.
 965          */
 966         struct module *lct_owner;
 967 };
 968
 969 #define LU_KEY_INIT(mod, type)                                    \
 970         static void* mod##_key_init(const struct lu_context *ctx, \
 971                                     struct lu_context_key *key)   \
 972         {                                                         \
 973                 type *value;                                      \
 974                                                                   \
 975                 CLASSERT(CFS_PAGE_SIZE >= sizeof (*value));       \
 976                                                                   \
 977                 OBD_ALLOC_PTR(value);                             \
 978                 if (value == NULL)                                \
 979                         value = ERR_PTR(-ENOMEM);                 \
 980                                                                   \
 981                 return value;                                     \
 982         }                                                         \
 983         struct __##mod##__dummy_init {;} /* semicolon catcher */
 984
 985 #define LU_KEY_FINI(mod, type)                                              \
 986         static void mod##_key_fini(const struct lu_context *ctx,            \
 987                                     struct lu_context_key *key, void* data) \
 988         {                                                                   \
 989                 type *info = data;                                          \
 990                                                                             \
 991                 OBD_FREE_PTR(info);                                         \
 992         }                                                                   \
 993         struct __##mod##__dummy_fini {;} /* semicolon catcher */
 994
 995 #define LU_KEY_INIT_FINI(mod, type)   \
 996         LU_KEY_INIT(mod,type);        \
 997         LU_KEY_FINI(mod,type)
 998
 999
1000 #define LU_CONTEXT_KEY_INIT(key)                        \
1001 do {                                                    \
1002         (key)->lct_owner = THIS_MODULE;                 \
1003 } while (0)
1004
1005 /*
1006  * Register new key.
1007  */
1008 int   lu_context_key_register(struct lu_context_key *key);
1009 /*
1010  * Deregister key.
1011  */
1012 void  lu_context_key_degister(struct lu_context_key *key);
1013 /*
1014  * Return value associated with key @key in context @ctx.
1015  */
1016 void *lu_context_key_get(const struct lu_context *ctx,
1017                          struct lu_context_key *key);
1018
1019 /*
1020  * Initialize context data-structure. Create values for all keys.
1021  */
1022 int  lu_context_init(struct lu_context *ctx, __u32 tags);
1023 /*
1024  * Finalize context data-structure. Destroy key values.
1025  */
1026 void lu_context_fini(struct lu_context *ctx);
1027
1028 /*
1029  * Called before entering context.
1030  */
1031 void lu_context_enter(struct lu_context *ctx);
1032 /*
1033  * Called after exiting from @ctx
1034  */
1035 void lu_context_exit(struct lu_context *ctx);
1036
1037 /*
1038  * Allocate for context all missing keys that were registered after context
1039  * creation.
1040  */
1041 int lu_context_refill(const struct lu_context *ctx);
1042
1043 /*
1044  * Environment.
1045  */
1046 struct lu_env {
1047         /*
1048          * "Local" context, used to store data instead of stack.
1049          */
1050         struct lu_context  le_ctx;
1051         /*
1052          * "Session" context for per-request data.
1053          */
1054         struct lu_context *le_ses;
1055 };
1056
1057 int  lu_env_init(struct lu_env *env, struct lu_context *ses, __u32 tags);
1058 void lu_env_fini(struct lu_env *env);
1059
1060 /*
1061  * Common name structure to be passed around for various name related methods.
1062  */
1063 struct lu_name {
1064         char    *ln_name;
1065         int      ln_namelen;
1066 };
1067
1068 /*
1069  * Common buffer structure to be passed around for various xattr_{s,g}et()
1070  * methods.
1071  */
1072 struct lu_buf {
1073         void   *lb_buf;
1074         ssize_t lb_len;
1075 };
1076
1077 extern struct lu_buf LU_BUF_NULL; /* null buffer */
1078
1079 #define DLUBUF "(%p %z)"
1080 #define PLUBUF(buf) (buf)->lb_buf, (buf)->lb_len
1081 /*
1082  * One-time initializers, called at obdclass module initialization, not
1083  * exported.
1084  */
1085
1086 /*
1087  * Initialization of global lu_* data.
1088  */
1089 int lu_global_init(void);
1090
1091 /*
1092  * Dual to lu_global_init().
1093  */
1094 void lu_global_fini(void);
1095
1096 enum {
1097         LU_TIME_FIND_LOOKUP,
1098         LU_TIME_FIND_ALLOC,
1099         LU_TIME_FIND_INSERT,
1100         LU_TIME_NR
1101 };
1102
1103 extern const char *lu_time_names[LU_TIME_NR];
1104
1105 #endif /* __LUSTRE_LU_OBJECT_H */