lustre/include/linux/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 __LINUX_LU_OBJECT_H
  24 #define __LINUX_LU_OBJECT_H
  25
  26 /*
  27  * struct ll_fid
  28  */
  29 #include <linux/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.
  87  *
  88  *
  89  *
  90  *
  91  *
  92  *
  93  *
  94  *
  95  *
  96  */
  97
  98 struct lu_site;
  99 struct lu_object;
 100 struct lu_device;
 101 struct lu_object_header;
 102
 103 /*
 104  * Operations common for data and meta-data devices.
 105  */
 106 struct lu_device_operations {
 107         /*
 108          * Object creation protocol.
 109          *
 110          * Due to design goal of avoiding recursion, object creation (see
 111          * lu_object_alloc()) is somewhat involved:
 112          *
 113          *  - first, ->ldo_object_alloc() method of the top-level device
 114          *  in the stack is called. It should allocate top level object
 115          *  (including lu_object_header), but without any lower-layer
 116          *  sub-object(s).
 117          *
 118          *  - then lu_object_alloc() sets fid in the header of newly created
 119          *  object.
 120          *
 121          *  - then ->ldo_object_init() is called. It has to allocate
 122          *  lower-layer object(s). To do this, ->ldo_object_init() calls
 123          *  ldo_object_alloc() of the lower-layer device(s).
 124          *
 125          *  - for all new objects allocated by ->ldo_object_init() (and
 126          *  inserted into object stack), ->ldo_object_init() is called again
 127          *  repeatedly, until no new objects are created.
 128          *
 129          */
 130         /*
 131          * Allocate lower-layer parts of the object by calling
 132          * ->ldo_object_alloc() of the corresponding underlying device.
 133          *
 134          * This method is called once for each object inserted into object
 135          * stack. It's responsibility of this method to insert lower-layer
 136          * object(s) it create into appropriate places of object stack.
 137          */
 138         int (*ldo_object_init)(struct lu_object *);
 139
 140         /*
 141          * Allocate object for the given device (without lower-layer
 142          * parts). This is called by ->ldo_object_init() from the parent
 143          * layer.
 144          */
 145         struct lu_object *(*ldo_object_alloc)(struct lu_device *);
 146
 147         /*
 148          * Dual to ->ldo_object_alloc(). Called when object is removed from
 149          * memory.
 150          */
 151         void (*ldo_object_free)(struct lu_object *o);
 152
 153         /*
 154          * Called when last active reference to the object is released (and
 155          * object returns to the cache).
 156          */
 157         void (*ldo_object_release)(struct lu_object *o);
 158
 159         /*
 160          * Debugging helper. Print given object.
 161          */
 162         int (*ldo_object_print)(struct seq_file *f, const struct lu_object *o);
 163 };
 164
 165 /*
 166  * Type of lu_device.
 167  */
 168 struct lu_device_type;
 169
 170 /*
 171  * Device: a layer in the server side abstraction stacking.
 172  */
 173 struct lu_device {
 174         /*
 175          * reference count. This is incremented, in particular, on each object
 176          * created at this layer.
 177          *
 178          * XXX which means that atomic_t is probably too small.
 179          */
 180         atomic_t                     ld_ref;
 181         struct lu_device_type       *ld_type;
 182         struct lu_device_operations *ld_ops;
 183         struct lu_site              *ld_site;
 184         struct proc_dir_entry       *ld_proc_entry;
 185
 186         /* XXX: temporary back pointer into obd. */
 187         struct obd_device           *ld_obd;
 188 };
 189
 190 struct lu_device_type_operations;
 191
 192 enum {
 193         /* this is meta-data device */
 194         LU_DEVICE_MD = (1 << 0),
 195         /* this is data device */
 196         LU_DEVICE_DT = (1 << 1)
 197 };
 198
 199 struct lu_device_type {
 200         __u32                             ldt_tags;
 201         char                             *ldt_name;
 202         struct lu_device_type_operations *ldt_ops;
 203 };
 204
 205 struct lu_device_type_operations {
 206         struct lu_device *(*ldto_device_alloc)(struct lu_device_type *t,
 207                                                struct lustre_cfg *lcfg);
 208         void (*ldto_device_free)(struct lu_device *d);
 209
 210         int  (*ldto_init)(struct lu_device_type *t);
 211         void (*ldto_fini)(struct lu_device_type *t);
 212 };
 213
 214 /*
 215  * Flags for the object layers.
 216  */
 217 enum lu_object_flags {
 218         /*
 219          * this flags is set if ->ldo_object_init() has been called for this
 220          * layer. Used by lu_object_alloc().
 221          */
 222         LU_OBJECT_ALLOCATED = (1 << 0)
 223 };
 224
 225 /*
 226  * Layer in the layered object.
 227  */
 228 struct lu_object {
 229         /*
 230          * Header for this object.
 231          */
 232         struct lu_object_header *lo_header;
 233         /*
 234          * Device for this layer.
 235          */
 236         struct lu_device        *lo_dev;
 237         /*
 238          * Linkage into list of all layers.
 239          */
 240         struct list_head         lo_linkage;
 241         /*
 242          * Depth. Top level layer depth is 0.
 243          */
 244         int                      lo_depth;
 245         /*
 246          * Flags from enum lu_object_flags.
 247          */
 248         unsigned long            lo_flags;
 249 };
 250
 251 enum lu_object_header_flags {
 252         /*
 253          * Don't keep this object in cache. Object will be destroyed as soon
 254          * as last reference to it is released. This flag cannot be cleared
 255          * once set.
 256          */
 257         LU_OBJECT_HEARD_BANSHEE = 0,
 258 };
 259
 260 /*
 261  * "Compound" object, consisting of multiple layers.
 262  */
 263 struct lu_object_header {
 264         /*
 265          * Object flags from enum lu_object_header_flags. Set and checked
 266          * atomically.
 267          */
 268         unsigned long     loh_flags;
 269         /*
 270          * Object reference count. Protected by site guard lock.
 271          */
 272         int               loh_ref;
 273         /*
 274          * Fid, uniquely identifying this object.
 275          */
 276         struct ll_fid     loh_fid;
 277         /*
 278          * Linkage into per-site hash table. Protected by site guard lock.
 279          */
 280         struct hlist_node loh_hash;
 281         /*
 282          * Linkage into per-site LRU list. Protected by site guard lock.
 283          */
 284         struct list_head  loh_lru;
 285         /*
 286          * Linkage into list of layers. Never modified once set (except lately
 287          * during object destruction). No locking is necessary.
 288          */
 289         struct list_head  loh_layers;
 290 };
 291
 292 /*
 293  * lu_site is a "compartment" within which objects are unique, and LRU
 294  * discipline is maintained.
 295  *
 296  * lu_site exists so that multiple layered stacks can co-exist in the same
 297  * address space.
 298  *
 299  */
 300 struct lu_site {
 301         /*
 302          * lock protecting:
 303          *
 304          *        - ->ls_hash hash table (and its linkages in objects);
 305          *
 306          *        - ->ls_lru list (and its linkages in objects);
 307          *
 308          *        - 0/1 transitions of object ->loh_ref reference count;
 309          *
 310          * yes, it's heavy.
 311          */
 312         spinlock_t         ls_guard;
 313         /*
 314          * Hash-table where objects are indexed by fid.
 315          */
 316         struct hlist_head *ls_hash;
 317         /*
 318          * Bit-mask for hash-table size.
 319          */
 320         int                ls_hash_mask;
 321
 322
 323         /*
 324          * LRU list, updated on each access to object. Protected by
 325          * ->ls_guard.
 326          *
 327          * "Cold" end of LRU is ->ls_lru.next. Accessed object are moved to
 328          * the ->ls_lru.prev (this is due to the non-existence of
 329          * list_for_each_entry_safe_reverse()).
 330          */
 331         struct list_head   ls_lru;
 332         /*
 333          * Total number of objects in this site. Protected by ->ls_guard.
 334          */
 335         unsigned           ls_total;
 336         /*
 337          * Total number of objects in this site with reference counter greater
 338          * than 0. Protected by ->ls_guard.
 339          */
 340         unsigned           ls_busy;
 341
 342         /*
 343          * Top-level device for this stack.
 344          */
 345         struct lu_device  *ls_top_dev;
 346
 347         /* statistical counters. Protected by nothing, races are accepted. */
 348         struct {
 349                 __u32 s_created;
 350                 __u32 s_cache_hit;
 351                 __u32 s_cache_miss;
 352                 /*
 353                  * Number of hash-table entry checks made.
 354                  *
 355                  *       ->s_cache_check / (->s_cache_miss + ->s_cache_hit)
 356                  *
 357                  * is an average number of hash slots inspected during single
 358                  * lookup.
 359                  */
 360                 __u32 s_cache_check;
 361                 /* raced cache insertions */
 362                 __u32 s_cache_race;
 363                 __u32 s_lru_purged;
 364         } ls_stats;
 365 };
 366
 367 /*
 368  * Helpers.
 369  */
 370 static inline struct lu_device_operations *
 371 lu_object_ops(const struct lu_object *o)
 372 {
 373         return o->lo_dev->ld_ops;
 374 }
 375
 376 static inline struct lu_object *lu_object_next(const struct lu_object *o)
 377 {
 378         return container_of(o->lo_linkage.next, struct lu_object, lo_linkage);
 379 }
 380
 381 static inline struct ll_fid *lu_object_fid(const struct lu_object *o)
 382 {
 383         return &o->lo_header->loh_fid;
 384 }
 385
 386 static inline struct lu_object *lu_object_top(struct lu_object_header *h)
 387 {
 388         LASSERT(!list_empty(&h->loh_layers));
 389         return container_of(h->loh_layers.next, struct lu_object, lo_linkage);
 390 }
 391
 392 static inline void lu_object_get(struct lu_object *o)
 393 {
 394         LASSERT(o->lo_header->loh_ref > 0);
 395         spin_lock(&o->lo_dev->ld_site->ls_guard);
 396         o->lo_header->loh_ref ++;
 397         spin_unlock(&o->lo_dev->ld_site->ls_guard);
 398 }
 399
 400 static inline int lu_object_is_dying(struct lu_object_header *h)
 401 {
 402         return test_bit(LU_OBJECT_HEARD_BANSHEE, &h->loh_flags);
 403 }
 404
 405 void lu_object_put(struct lu_object *o);
 406 void lu_site_purge(struct lu_site *s, int nr);
 407 int lu_object_print(struct seq_file *f, const struct lu_object *o);
 408 struct lu_object *lu_object_find(struct lu_site *s, const struct ll_fid *f);
 409
 410 int  lu_site_init(struct lu_site *s, struct lu_device *top);
 411 void lu_site_fini(struct lu_site *s);
 412
 413 void lu_device_get(struct lu_device *d);
 414 void lu_device_put(struct lu_device *d);
 415
 416 int lu_device_init(struct lu_device *d, struct lu_device_type *t);
 417 void lu_device_fini(struct lu_device *d);
 418
 419 int lu_object_init(struct lu_object *o,
 420                    struct lu_object_header *h, struct lu_device *d);
 421 void lu_object_fini(struct lu_object *o);
 422 void lu_object_add_top(struct lu_object_header *h, struct lu_object *o);
 423 void lu_object_add(struct lu_object *before, struct lu_object *o);
 424
 425 int lu_object_header_init(struct lu_object_header *h);
 426 void lu_object_header_fini(struct lu_object_header *h);
 427
 428 #endif /* __LINUX_OBD_CLASS_H */