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
  39 struct seq_file;
  40 struct proc_dir_entry;
  41 struct lustre_cfg;
  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 /*
  98  * Operations common for data and meta-data devices.
  99  */
 100 struct lu_device_operations {
 101         /*
 102          * Object creation protocol.
 103          *
 104          * Due to design goal of avoiding recursion, object creation (see
 105          * lu_object_alloc()) is somewhat involved:
 106          *
 107          *  - first, ->ldo_object_alloc() method of the top-level device
 108          *  in the stack is called. It should allocate top level object
 109          *  (including lu_object_header), but without any lower-layer
 110          *  sub-object(s).
 111          *
 112          *  - then lu_object_alloc() sets fid in the header of newly created
 113          *  object.
 114          *
 115          *  - then ->loo_object_init() (a method from struct
 116          *  lu_object_operations) is called. It has to allocate lower-layer
 117          *  object(s). To do this, ->loo_object_init() calls
 118          *  ldo_object_alloc() of the lower-layer device(s).
 119          *
 120          *  - for all new objects allocated by ->loo_object_init() (and
 121          *  inserted into object stack), ->loo_object_init() is called again
 122          *  repeatedly, until no new objects are created.
 123          *
 124          */
 125
 126         /*
 127          * Allocate object for the given device (without lower-layer
 128          * parts). This is called by ->loo_object_init() from the parent
 129          * layer, and should setup at least ->lo_dev and ->lo_ops fields of
 130          * resulting lu_object.
 131          *
 132          * postcondition: ergo(!IS_ERR(result), result->lo_dev ==  d &&
 133          *                                      result->lo_ops != NULL);
 134          */
 135         struct lu_object *(*ldo_object_alloc)(const struct lu_context *ctx,
 136                                               const struct lu_object_header *h,
 137                                               struct lu_device *d);
 138         /*
 139          * process config specific for device
 140          */
 141         int (*ldo_process_config)(const struct lu_context *ctx,
 142                                   struct lu_device *, struct lustre_cfg *);
 143         int (*ldo_recovery_complete)(const struct lu_context *,
 144                                      struct lu_device *);
 145
 146 };
 147
 148 /*
 149  * Type of "printer" function used by ->loo_object_print() method.
 150  *
 151  * Printer function is needed to provide some flexibility in (semi-)debugging
 152  * output: possible implementations: printk, CDEBUG, sysfs/seq_file
 153  */
 154 typedef int (*lu_printer_t)(const struct lu_context *ctx,
 155                             void *cookie, const char *format, ...)
 156         __attribute__ ((format (printf, 3, 4)));
 157
 158 /*
 159  * Operations specific for particular lu_object.
 160  */
 161 struct lu_object_operations {
 162
 163         /*
 164          * Allocate lower-layer parts of the object by calling
 165          * ->ldo_object_alloc() of the corresponding underlying device.
 166          *
 167          * This method is called once for each object inserted into object
 168          * stack. It's responsibility of this method to insert lower-layer
 169          * object(s) it create into appropriate places of object stack.
 170          */
 171         int (*loo_object_init)(const struct lu_context *ctx,
 172                                struct lu_object *o);
 173         /*
 174          * Called (in top-to-bottom order) during object allocation after all
 175          * layers were allocated and initialized. Can be used to perform
 176          * initialization depending on lower layers.
 177          */
 178         int (*loo_object_start)(const struct lu_context *ctx,
 179                                 struct lu_object *o);
 180         /*
 181          * Called before ->loo_object_free() to signal that object is being
 182          * destroyed. Dual to ->loo_object_init().
 183          */
 184         void (*loo_object_delete)(const struct lu_context *ctx,
 185                                   struct lu_object *o);
 186
 187         /*
 188          * Dual to ->ldo_object_alloc(). Called when object is removed from
 189          * memory.
 190          */
 191         void (*loo_object_free)(const struct lu_context *ctx,
 192                                 struct lu_object *o);
 193
 194         /*
 195          * Called when last active reference to the object is released (and
 196          * object returns to the cache). This method is optional.
 197          */
 198         void (*loo_object_release)(const struct lu_context *ctx,
 199                                    struct lu_object *o);
 200         /*
 201          * Debugging helper. Print given object.
 202          */
 203         int (*loo_object_print)(const struct lu_context *ctx, void *cookie,
 204                                 lu_printer_t p, const struct lu_object *o);
 205         /*
 206          * Optional debugging method. Returns true iff method is internally
 207          * consistent.
 208          */
 209         int (*loo_object_invariant)(const struct lu_object *o);
 210 };
 211
 212 /*
 213  * Type of lu_device.
 214  */
 215 struct lu_device_type;
 216
 217 /*
 218  * Device: a layer in the server side abstraction stacking.
 219  */
 220 struct lu_device {
 221         /*
 222          * reference count. This is incremented, in particular, on each object
 223          * created at this layer.
 224          *
 225          * XXX which means that atomic_t is probably too small.
 226          */
 227         atomic_t                     ld_ref;
 228         /*
 229          * Pointer to device type. Never modified once set.
 230          */
 231         struct lu_device_type       *ld_type;
 232         /*
 233          * Operation vector for this device.
 234          */
 235         struct lu_device_operations *ld_ops;
 236         /*
 237          * Stack this device belongs to.
 238          */
 239         struct lu_site              *ld_site;
 240         struct proc_dir_entry       *ld_proc_entry;
 241
 242         /* XXX: temporary back pointer into obd. */
 243         struct obd_device           *ld_obd;
 244 };
 245
 246 struct lu_device_type_operations;
 247
 248 /*
 249  * Tag bits for device type. They are used to distinguish certain groups of
 250  * device types.
 251  */
 252 enum lu_device_tag {
 253         /* this is meta-data device */
 254         LU_DEVICE_MD = (1 << 0),
 255         /* this is data device */
 256         LU_DEVICE_DT = (1 << 1)
 257 };
 258
 259 /*
 260  * Type of device.
 261  */
 262 struct lu_device_type {
 263         /*
 264          * Tag bits. Taken from enum lu_device_tag. Never modified once set.
 265          */
 266         __u32                             ldt_tags;
 267         /*
 268          * Name of this class. Unique system-wide. Never modified once set.
 269          */
 270         char                             *ldt_name;
 271         /*
 272          * Operations for this type.
 273          */
 274         struct lu_device_type_operations *ldt_ops;
 275         /*
 276          * XXX: temporary pointer to associated obd_type.
 277          */
 278         struct obd_type                  *ldt_obd_type;
 279         /*
 280          * XXX: temporary: context tags used by obd_*() calls.
 281          */
 282         __u32                             ldt_ctx_tags;
 283 };
 284
 285 /*
 286  * Operations on a device type.
 287  */
 288 struct lu_device_type_operations {
 289         /*
 290          * Allocate new device.
 291          */
 292         struct lu_device *(*ldto_device_alloc)(const struct lu_context *ctx,
 293                                                struct lu_device_type *t,
 294                                                struct lustre_cfg *lcfg);
 295         /*
 296          * Free device. Dual to ->ldto_device_alloc().
 297          */
 298         void (*ldto_device_free)(const struct lu_context *,
 299                                  struct lu_device *);
 300
 301         /*
 302          * Initialize the devices after allocation
 303          */
 304         int  (*ldto_device_init)(const struct lu_context *ctx,
 305                                  struct lu_device *, struct lu_device *);
 306         /*
 307          * Finalize device. Dual to ->ldto_device_init(). Returns pointer to
 308          * the next device in the stack.
 309          */
 310         struct lu_device *(*ldto_device_fini)(const struct lu_context *ctx,
 311                                               struct lu_device *);
 312
 313         /*
 314          * Initialize device type. This is called on module load.
 315          */
 316         int  (*ldto_init)(struct lu_device_type *t);
 317         /*
 318          * Finalize device type. Dual to ->ldto_init(). Called on module
 319          * unload.
 320          */
 321         void (*ldto_fini)(struct lu_device_type *t);
 322 };
 323
 324 /*
 325  * Flags for the object layers.
 326  */
 327 enum lu_object_flags {
 328         /*
 329          * this flags is set if ->loo_object_init() has been called for this
 330          * layer. Used by lu_object_alloc().
 331          */
 332         LU_OBJECT_ALLOCATED = (1 << 0)
 333 };
 334
 335 /*
 336  * Common object attributes.
 337  */
 338 /* valid flags */
 339 enum la_valid {
 340         /*mapped ATTR flag*/
 341         LA_ATIME = 1 << 0,
 342         LA_MTIME = 1 << 1,
 343         LA_CTIME = 1 << 2,
 344         LA_SIZE  = 1 << 3,
 345         LA_MODE  = 1 << 4,
 346         LA_UID   = 1 << 5,
 347         LA_GID   = 1 << 6,
 348         LA_BLOCKS = 1 << 7,
 349         LA_TYPE   = 1 << 8,
 350         LA_FLAGS  = 1 << 9,
 351         LA_NLINK  = 1 << 10,
 352         LA_RDEV   = 1 << 11,
 353         LA_BLKSIZE = 1 << 12,
 354 };
 355
 356 struct lu_attr {
 357         __u64          la_size;   /* size in bytes */
 358         __u64          la_mtime;  /* modification time in seconds since Epoch */
 359         __u64          la_atime;  /* access time in seconds since Epoch */
 360         __u64          la_ctime;  /* change time in seconds since Epoch */
 361         __u64          la_blocks; /* 512-byte blocks allocated to object */
 362         __u32          la_mode;   /* permission bits and file type */
 363         __u32          la_uid;    /* owner id */
 364         __u32          la_gid;    /* group id */
 365         __u32          la_flags;  /* object flags */
 366         __u32          la_nlink;  /* number of persistent references to this
 367                                    * object */
 368         __u32          la_blksize; /* blk size of the object*/
 369
 370         __u32          la_rdev;   /* real device */
 371         __u64          la_valid;  /* valid bits */
 372 };
 373
 374
 375 /*
 376  * Layer in the layered object.
 377  */
 378 struct lu_object {
 379         /*
 380          * Header for this object.
 381          */
 382         struct lu_object_header     *lo_header;
 383         /*
 384          * Device for this layer.
 385          */
 386         struct lu_device            *lo_dev;
 387         /*
 388          * Operations for this object.
 389          */
 390         struct lu_object_operations *lo_ops;
 391         /*
 392          * Linkage into list of all layers.
 393          */
 394         struct list_head             lo_linkage;
 395         /*
 396          * Depth. Top level layer depth is 0.
 397          */
 398         int                          lo_depth;
 399         /*
 400          * Flags from enum lu_object_flags.
 401          */
 402         unsigned long                lo_flags;
 403 };
 404
 405 enum lu_object_header_flags {
 406         /*
 407          * Don't keep this object in cache. Object will be destroyed as soon
 408          * as last reference to it is released. This flag cannot be cleared
 409          * once set.
 410          */
 411         LU_OBJECT_HEARD_BANSHEE = 0,
 412 };
 413
 414 enum lu_object_header_attr {
 415         LOHA_EXISTS   = 1 << 0,
 416         LOHA_REMOTE   = 1 << 1,
 417         /*
 418          * UNIX file type is stored in S_IFMT bits.
 419          */
 420         LOHA_FT_START = 1 << 12, /* S_IFIFO */
 421         LOHA_FT_END   = 1 << 15, /* S_IFREG */
 422 };
 423
 424 /*
 425  * "Compound" object, consisting of multiple layers.
 426  *
 427  * Compound object with given fid is unique with given lu_site.
 428  *
 429  * Note, that object does *not* necessary correspond to the real object in the
 430  * persistent storage: object is an anchor for locking and method calling, so
 431  * it is created for things like not-yet-existing child created by mkdir or
 432  * create calls. ->loo_exists() can be used to check whether object is backed
 433  * by persistent storage entity.
 434  */
 435 struct lu_object_header {
 436         /*
 437          * Object flags from enum lu_object_header_flags. Set and checked
 438          * atomically.
 439          */
 440         unsigned long     loh_flags;
 441         /*
 442          * Object reference count. Protected by site guard lock.
 443          */
 444         int               loh_ref;
 445         /*
 446          * Fid, uniquely identifying this object.
 447          */
 448         struct lu_fid     loh_fid;
 449         /*
 450          * Common object attributes, cached for efficiency. From enum
 451          * lu_object_header_attr.
 452          */
 453         __u32             loh_attr;
 454         /*
 455          * Linkage into per-site hash table. Protected by site guard lock.
 456          */
 457         struct hlist_node loh_hash;
 458         /*
 459          * Linkage into per-site LRU list. Protected by site guard lock.
 460          */
 461         struct list_head  loh_lru;
 462         /*
 463          * Linkage into list of layers. Never modified once set (except lately
 464          * during object destruction). No locking is necessary.
 465          */
 466         struct list_head  loh_layers;
 467 };
 468
 469 struct fld;
 470
 471 /*
 472  * lu_site is a "compartment" within which objects are unique, and LRU
 473  * discipline is maintained.
 474  *
 475  * lu_site exists so that multiple layered stacks can co-exist in the same
 476  * address space.
 477  *
 478  * lu_site has the same relation to lu_device as lu_object_header to
 479  * lu_object.
 480  */
 481 struct lu_site {
 482         /*
 483          * lock protecting:
 484          *
 485          *        - ->ls_hash hash table (and its linkages in objects);
 486          *
 487          *        - ->ls_lru list (and its linkages in objects);
 488          *
 489          *        - 0/1 transitions of object ->loh_ref reference count;
 490          *
 491          * yes, it's heavy.
 492          */
 493         spinlock_t            ls_guard;
 494         /*
 495          * Hash-table where objects are indexed by fid.
 496          */
 497         struct hlist_head    *ls_hash;
 498         /*
 499          * Bit-mask for hash-table size.
 500          */
 501         int                   ls_hash_mask;
 502
 503         /*
 504          * LRU list, updated on each access to object. Protected by
 505          * ->ls_guard.
 506          *
 507          * "Cold" end of LRU is ->ls_lru.next. Accessed object are moved to
 508          * the ->ls_lru.prev (this is due to the non-existence of
 509          * list_for_each_entry_safe_reverse()).
 510          */
 511         struct list_head      ls_lru;
 512         /*
 513          * Total number of objects in this site. Protected by ->ls_guard.
 514          */
 515         unsigned              ls_total;
 516         /*
 517          * Total number of objects in this site with reference counter greater
 518          * than 0. Protected by ->ls_guard.
 519          */
 520         unsigned              ls_busy;
 521
 522         /*
 523          * Top-level device for this stack.
 524          */
 525         struct lu_device     *ls_top_dev;
 526         /*
 527          * mds number of this site.
 528          */
 529         mdsno_t               ls_node_id;
 530         /*
 531          * Fid location database
 532          */
 533         struct lu_server_fld *ls_server_fld;
 534         struct lu_client_fld *ls_client_fld;
 535
 536         /*
 537          * Server Seq Manager
 538          */
 539         struct lu_server_seq *ls_server_seq;
 540
 541         /*
 542          * Controller Seq Manager
 543          */
 544         struct lu_server_seq *ls_control_seq;
 545
 546         /*
 547          * Client Seq Manager
 548          */
 549         struct lu_client_seq *ls_client_seq;
 550         struct obd_export    *ls_client_exp;
 551
 552         /* statistical counters. Protected by nothing, races are accepted. */
 553         struct {
 554                 __u32 s_created;
 555                 __u32 s_cache_hit;
 556                 __u32 s_cache_miss;
 557                 /*
 558                  * Number of hash-table entry checks made.
 559                  *
 560                  *       ->s_cache_check / (->s_cache_miss + ->s_cache_hit)
 561                  *
 562                  * is an average number of hash slots inspected during single
 563                  * lookup.
 564                  */
 565                 __u32 s_cache_check;
 566                 /* raced cache insertions */
 567                 __u32 s_cache_race;
 568                 __u32 s_lru_purged;
 569         } ls_stats;
 570 };
 571
 572 /*
 573  * Constructors/destructors.
 574  */
 575
 576 /*
 577  * Initialize site @s, with @d as the top level device.
 578  */
 579 int  lu_site_init(struct lu_site *s, struct lu_device *d);
 580 /*
 581  * Finalize @s and release its resources.
 582  */
 583 void lu_site_fini(struct lu_site *s);
 584
 585 /*
 586  * Acquire additional reference on device @d
 587  */
 588 void lu_device_get(struct lu_device *d);
 589 /*
 590  * Release reference on device @d.
 591  */
 592 void lu_device_put(struct lu_device *d);
 593
 594 /*
 595  * Initialize device @d of type @t.
 596  */
 597 int lu_device_init(struct lu_device *d, struct lu_device_type *t);
 598 /*
 599  * Finalize device @d.
 600  */
 601 void lu_device_fini(struct lu_device *d);
 602
 603 /*
 604  * Initialize compound object.
 605  */
 606 int lu_object_header_init(struct lu_object_header *h);
 607 /*
 608  * Finalize compound object.
 609  */
 610 void lu_object_header_fini(struct lu_object_header *h);
 611
 612 /*
 613  * Initialize object @o that is part of compound object @h and was created by
 614  * device @d.
 615  */
 616 int lu_object_init(struct lu_object *o,
 617                    struct lu_object_header *h, struct lu_device *d);
 618 /*
 619  * Finalize object and release its resources.
 620  */
 621 void lu_object_fini(struct lu_object *o);
 622 /*
 623  * Add object @o as first layer of compound object @h.
 624  *
 625  * This is typically called by the ->ldo_object_alloc() method of top-level
 626  * device.
 627  */
 628 void lu_object_add_top(struct lu_object_header *h, struct lu_object *o);
 629 /*
 630  * Add object @o as a layer of compound object, going after @before.1
 631  *
 632  * This is typically called by the ->ldo_object_alloc() method of
 633  * @before->lo_dev.
 634  */
 635 void lu_object_add(struct lu_object *before, struct lu_object *o);
 636
 637 /*
 638  * Caching and reference counting.
 639  */
 640
 641 /*
 642  * Acquire additional reference to the given object. This function is used to
 643  * attain additional reference. To acquire initial reference use
 644  * lu_object_find().
 645  */
 646 static inline void lu_object_get(struct lu_object *o)
 647 {
 648         LASSERT(o->lo_header->loh_ref > 0);
 649         spin_lock(&o->lo_dev->ld_site->ls_guard);
 650         o->lo_header->loh_ref ++;
 651         spin_unlock(&o->lo_dev->ld_site->ls_guard);
 652 }
 653
 654 /*
 655  * Return true of object will not be cached after last reference to it is
 656  * released.
 657  */
 658 static inline int lu_object_is_dying(const struct lu_object_header *h)
 659 {
 660         return test_bit(LU_OBJECT_HEARD_BANSHEE, &h->loh_flags);
 661 }
 662
 663 /*
 664  * Decrease reference counter on object. If last reference is freed, return
 665  * object to the cache, unless lu_object_is_dying(o) holds. In the latter
 666  * case, free object immediately.
 667  */
 668 void lu_object_put(const struct lu_context *ctxt,
 669                    struct lu_object *o);
 670
 671 /*
 672  * Free @nr objects from the cold end of the site LRU list.
 673  */
 674 void lu_site_purge(const struct lu_context *ctx,
 675                    struct lu_site *s, int nr);
 676
 677 /*
 678  * Search cache for an object with the fid @f. If such object is found, return
 679  * it. Otherwise, create new object, insert it into cache and return it. In
 680  * any case, additional reference is acquired on the returned object.
 681  */
 682 struct lu_object *lu_object_find(const struct lu_context *ctxt,
 683                                  struct lu_site *s, const struct lu_fid *f);
 684
 685 /*
 686  * Helpers.
 687  */
 688
 689 /*
 690  * First (topmost) sub-object of given compound object
 691  */
 692 static inline struct lu_object *lu_object_top(struct lu_object_header *h)
 693 {
 694         LASSERT(!list_empty(&h->loh_layers));
 695         return container_of0(h->loh_layers.next, struct lu_object, lo_linkage);
 696 }
 697
 698 /*
 699  * Next sub-object in the layering
 700  */
 701 static inline struct lu_object *lu_object_next(const struct lu_object *o)
 702 {
 703         return container_of0(o->lo_linkage.next, struct lu_object, lo_linkage);
 704 }
 705
 706 /*
 707  * Pointer to the fid of this object.
 708  */
 709 static inline const struct lu_fid *lu_object_fid(const struct lu_object *o)
 710 {
 711         return &o->lo_header->loh_fid;
 712 }
 713
 714 /*
 715  * return device operations vector for this object
 716  */
 717 static inline struct lu_device_operations *
 718 lu_object_ops(const struct lu_object *o)
 719 {
 720         return o->lo_dev->ld_ops;
 721 }
 722
 723 /*
 724  * Given a compound object, find its slice, corresponding to the device type
 725  * @dtype.
 726  */
 727 struct lu_object *lu_object_locate(struct lu_object_header *h,
 728                                    struct lu_device_type *dtype);
 729
 730 struct lu_cdebug_print_info {
 731         int         lpi_subsys;
 732         int         lpi_mask;
 733         const char *lpi_file;
 734         const char *lpi_fn;
 735         int         lpi_line;
 736 };
 737
 738 /*
 739  * Printer function emitting messages through libcfs_debug_msg().
 740  */
 741 int lu_cdebug_printer(const struct lu_context *ctx,
 742                       void *cookie, const char *format, ...);
 743
 744 /*
 745  * Print object description followed by user-supplied message.
 746  */
 747 #define LU_OBJECT_DEBUG(mask, ctx, object, format, ...)                 \
 748 ({                                                                      \
 749         static struct lu_cdebug_print_info __info = {                   \
 750                 .lpi_subsys = DEBUG_SUBSYSTEM,                          \
 751                 .lpi_mask   = (mask),                                   \
 752                 .lpi_file   = __FILE__,                                 \
 753                 .lpi_fn     = __FUNCTION__,                             \
 754                 .lpi_line   = __LINE__                                  \
 755         };                                                              \
 756         lu_object_print(ctx, &__info, lu_cdebug_printer, object);       \
 757         CDEBUG(mask, format , ## __VA_ARGS__);                          \
 758 })
 759
 760 /*
 761  * Print human readable representation of the @o to the @f.
 762  */
 763 void lu_object_print(const struct lu_context *ctxt, void *cookie,
 764                      lu_printer_t printer, const struct lu_object *o);
 765
 766 /*
 767  * Check object consistency.
 768  */
 769 int lu_object_invariant(const struct lu_object *o);
 770
 771 /*
 772  * Returns 1 iff object @o exists on the stable storage,
 773  * returns -1 iff object @o is on remote server.
 774  */
 775 static inline int lu_object_exists(const struct lu_object *o)
 776 {
 777         __u32 attr;
 778
 779         attr = o->lo_header->loh_attr;
 780         if (attr & LOHA_REMOTE)
 781                 return -1;
 782         else if (attr & LOHA_EXISTS)
 783                 return +1;
 784         else
 785                 return 0;
 786 }
 787
 788 static inline int lu_object_assert_exists(const struct lu_object *o)
 789 {
 790         return lu_object_exists(o) != 0;
 791 }
 792
 793 static inline int lu_object_assert_not_exists(const struct lu_object *o)
 794 {
 795         return lu_object_exists(o) <= 0;
 796 }
 797
 798 /*
 799  * Attr of this object.
 800  */
 801 static inline const __u32 lu_object_attr(const struct lu_object *o)
 802 {
 803         LASSERT(lu_object_exists(o) > 0);
 804         return o->lo_header->loh_attr;
 805 }
 806
 807 struct lu_rdpg {
 808         /* input params, should be filled out by mdt */
 809         __u32                   rp_hash;        /* hash */
 810         int                     rp_count;       /* count in bytes       */
 811         int                     rp_npages;      /* number of pages      */
 812         struct page           **rp_pages;       /* pointers to pages    */
 813 };
 814
 815 enum lu_xattr_flags {
 816         LU_XATTR_REPLACE = (1 << 0),
 817         LU_XATTR_CREATE  = (1 << 1)
 818 };
 819
 820 /*
 821  * lu_context. Execution context for lu_object methods. Currently associated
 822  * with thread.
 823  *
 824  * All lu_object methods, except device and device type methods (called during
 825  * system initialization and shutdown) are executed "within" some
 826  * lu_context. This means, that pointer to some "current" lu_context is passed
 827  * as an argument to all methods.
 828  *
 829  * All service ptlrpc threads create lu_context as part of their
 830  * initialization. It is possible to create "stand-alone" context for other
 831  * execution environments (like system calls).
 832  *
 833  * lu_object methods mainly use lu_context through lu_context_key interface
 834  * that allows each layer to associate arbitrary pieces of data with each
 835  * context (see pthread_key_create(3) for similar interface).
 836  *
 837  */
 838 struct lu_context {
 839         /*
 840          * Theoretically we'd want to use lu_objects and lu_contexts on the
 841          * client side too. On the other hand, we don't want to allocate
 842          * values of server-side keys for the client contexts and vice versa.
 843          *
 844          * To achieve this, set of tags in introduced. Contexts and keys are
 845          * marked with tags. Key value are created only for context whose set
 846          * of tags has non-empty intersection with one for key. Tags are taken
 847          * from enum lu_context_tag.
 848          */
 849         __u32                  lc_tags;
 850         /*
 851          * Pointer to the home service thread. NULL for other execution
 852          * contexts.
 853          */
 854         struct ptlrpc_thread  *lc_thread;
 855         /*
 856          * Pointer to an array with key values. Internal implementation
 857          * detail.
 858          */
 859         void                 **lc_value;
 860 };
 861
 862 /*
 863  * lu_context_key interface. Similar to pthread_key.
 864  */
 865
 866 enum lu_context_tag {
 867         LCT_MD_THREAD = 1 << 0,
 868         LCT_DT_THREAD = 1 << 1,
 869         LCT_TX_HANDLE = 1 << 2,
 870         LCT_CL_THREAD = 1 << 3
 871 };
 872
 873 /*
 874  * Key. Represents per-context value slot.
 875  */
 876 struct lu_context_key {
 877         /*
 878          * Set of tags for which values of this key are to be instantiated.
 879          */
 880         __u32 lct_tags;
 881         /*
 882          * Value constructor. This is called when new value is created for a
 883          * context. Returns pointer to new value of error pointer.
 884          */
 885         void  *(*lct_init)(const struct lu_context *ctx,
 886                            struct lu_context_key *key);
 887         /*
 888          * Value destructor. Called when context with previously allocated
 889          * value of this slot is destroyed. @data is a value that was returned
 890          * by a matching call to ->lct_init().
 891          */
 892         void   (*lct_fini)(const struct lu_context *ctx,
 893                            struct lu_context_key *key, void *data);
 894         /*
 895          * Optional method called on lu_context_exit() for all allocated
 896          * keys. Can be used by debugging code checking that locks are
 897          * released, etc.
 898          */
 899         void   (*lct_exit)(const struct lu_context *ctx,
 900                            struct lu_context_key *key, void *data);
 901         /*
 902          * Internal implementation detail: index within ->lc_value[] reserved
 903          * for this key.
 904          */
 905         int      lct_index;
 906         /*
 907          * Internal implementation detail: number of values created for this
 908          * key.
 909          */
 910         unsigned lct_used;
 911 };
 912
 913 /*
 914  * Register new key.
 915  */
 916 int   lu_context_key_register(struct lu_context_key *key);
 917 /*
 918  * Deregister key.
 919  */
 920 void  lu_context_key_degister(struct lu_context_key *key);
 921 /*
 922  * Return value associated with key @key in context @ctx.
 923  */
 924 void *lu_context_key_get(const struct lu_context *ctx,
 925                          struct lu_context_key *key);
 926
 927 /*
 928  * Initialize context data-structure. Create values for all keys.
 929  */
 930 int  lu_context_init(struct lu_context *ctx, __u32 tags);
 931 /*
 932  * Finalize context data-structure. Destroy key values.
 933  */
 934 void lu_context_fini(struct lu_context *ctx);
 935
 936 /*
 937  * Called before entering context.
 938  */
 939 void lu_context_enter(struct lu_context *ctx);
 940 /*
 941  * Called after exiting from @ctx
 942  */
 943 void lu_context_exit(struct lu_context *ctx);
 944
 945 /*
 946  * Allocate for context all missing keys that were registered after context
 947  * creation.
 948  */
 949 int lu_context_refill(const struct lu_context *ctx);
 950
 951 /*
 952  * One-time initializers, called at obdclass module initialization, not
 953  * exported.
 954  */
 955
 956 /*
 957  * Initialization of global lu_* data.
 958  */
 959 int lu_global_init(void);
 960
 961 /*
 962  * Dual to lu_global_init().
 963  */
 964 void lu_global_fini(void);
 965
 966 #endif /* __LUSTRE_LU_OBJECT_H */