Whamcloud - gitweb
953c34c579c43dd9dc14e9120ee2b0d036788e6f
[fs/lustre-release.git] / lustre / include / lu_object.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, but
11  * WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * General Public License version 2 for more details (a copy is included
14  * in the LICENSE file that accompanied this code).
15  *
16  * You should have received a copy of the GNU General Public License
17  * version 2 along with this program; If not, see
18  * http://www.sun.com/software/products/lustre/docs/GPLv2.pdf
19  *
20  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
21  * CA 95054 USA or visit www.sun.com if you need additional information or
22  * have any questions.
23  *
24  * GPL HEADER END
25  */
26 /*
27  * Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
28  * Use is subject to license terms.
29  *
30  * Copyright (c) 2011, 2012, Whamcloud, Inc.
31  */
32 /*
33  * This file is part of Lustre, http://www.lustre.org/
34  * Lustre is a trademark of Sun Microsystems, Inc.
35  */
36
37 #ifndef __LUSTRE_LU_OBJECT_H
38 #define __LUSTRE_LU_OBJECT_H
39
40 #include <stdarg.h>
41
42 /*
43  * struct lu_fid
44  */
45 #include <libcfs/libcfs.h>
46
47 #include <lustre/lustre_idl.h>
48
49 #include <lu_ref.h>
50
51 struct seq_file;
52 struct proc_dir_entry;
53 struct lustre_cfg;
54 struct lprocfs_stats;
55
56 /** \defgroup lu lu
57  * lu_* data-types represent server-side entities shared by data and meta-data
58  * stacks.
59  *
60  * Design goals:
61  *
62  * -# support for layering.
63  *
64  *     Server side object is split into layers, one per device in the
65  *     corresponding device stack. Individual layer is represented by struct
66  *     lu_object. Compound layered object --- by struct lu_object_header. Most
67  *     interface functions take lu_object as an argument and operate on the
68  *     whole compound object. This decision was made due to the following
69  *     reasons:
70  *
71  *        - it's envisaged that lu_object will be used much more often than
72  *        lu_object_header;
73  *
74  *        - we want lower (non-top) layers to be able to initiate operations
75  *        on the whole object.
76  *
77  *     Generic code supports layering more complex than simple stacking, e.g.,
78  *     it is possible that at some layer object "spawns" multiple sub-objects
79  *     on the lower layer.
80  *
81  * -# fid-based identification.
82  *
83  *     Compound object is uniquely identified by its fid. Objects are indexed
84  *     by their fids (hash table is used for index).
85  *
86  * -# caching and life-cycle management.
87  *
88  *     Object's life-time is controlled by reference counting. When reference
89  *     count drops to 0, object is returned to cache. Cached objects still
90  *     retain their identity (i.e., fid), and can be recovered from cache.
91  *
92  *     Objects are kept in the global LRU list, and lu_site_purge() function
93  *     can be used to reclaim given number of unused objects from the tail of
94  *     the LRU.
95  *
96  * -# avoiding recursion.
97  *
98  *     Generic code tries to replace recursion through layers by iterations
99  *     where possible. Additionally to the end of reducing stack consumption,
100  *     data, when practically possible, are allocated through lu_context_key
101  *     interface rather than on stack.
102  * @{
103  */
104
105 struct lu_site;
106 struct lu_object;
107 struct lu_device;
108 struct lu_object_header;
109 struct lu_context;
110 struct lu_env;
111
112 /**
113  * Operations common for data and meta-data devices.
114  */
115 struct lu_device_operations {
116         /**
117          * Allocate object for the given device (without lower-layer
118          * parts). This is called by lu_object_operations::loo_object_init()
119          * from the parent layer, and should setup at least lu_object::lo_dev
120          * and lu_object::lo_ops fields of resulting lu_object.
121          *
122          * Object creation protocol.
123          *
124          * Due to design goal of avoiding recursion, object creation (see
125          * lu_object_alloc()) is somewhat involved:
126          *
127          *  - first, lu_device_operations::ldo_object_alloc() method of the
128          *  top-level device in the stack is called. It should allocate top
129          *  level object (including lu_object_header), but without any
130          *  lower-layer sub-object(s).
131          *
132          *  - then lu_object_alloc() sets fid in the header of newly created
133          *  object.
134          *
135          *  - then lu_object_operations::loo_object_init() is called. It has
136          *  to allocate lower-layer object(s). To do this,
137          *  lu_object_operations::loo_object_init() calls ldo_object_alloc()
138          *  of the lower-layer device(s).
139          *
140          *  - for all new objects allocated by
141          *  lu_object_operations::loo_object_init() (and inserted into object
142          *  stack), lu_object_operations::loo_object_init() is called again
143          *  repeatedly, until no new objects are created.
144          *
145          * \post ergo(!IS_ERR(result), result->lo_dev == d &&
146          *                             result->lo_ops != NULL);
147          */
148         struct lu_object *(*ldo_object_alloc)(const struct lu_env *env,
149                                               const struct lu_object_header *h,
150                                               struct lu_device *d);
151         /**
152          * process config specific for device.
153          */
154         int (*ldo_process_config)(const struct lu_env *env,
155                                   struct lu_device *, struct lustre_cfg *);
156         int (*ldo_recovery_complete)(const struct lu_env *,
157                                      struct lu_device *);
158
159         /**
160          * initialize local objects for device. this method called after layer has
161          * been initialized (after LCFG_SETUP stage) and before it starts serving
162          * user requests.
163          */
164
165         int (*ldo_prepare)(const struct lu_env *,
166                            struct lu_device *parent,
167                            struct lu_device *dev);
168
169 };
170
171 /**
172  * For lu_object_conf flags
173  */
174 typedef enum {
175         /* This is a new object to be allocated, or the file
176          * corresponding to the object does not exists. */
177         LOC_F_NEW       = 0x00000001,
178 } loc_flags_t;
179
180 /**
181  * Object configuration, describing particulars of object being created. On
182  * server this is not used, as server objects are full identified by fid. On
183  * client configuration contains struct lustre_md.
184  */
185 struct lu_object_conf {
186         /**
187          * Some hints for obj find and alloc.
188          */
189         loc_flags_t     loc_flags;
190 };
191
192 /**
193  * Type of "printer" function used by lu_object_operations::loo_object_print()
194  * method.
195  *
196  * Printer function is needed to provide some flexibility in (semi-)debugging
197  * output: possible implementations: printk, CDEBUG, sysfs/seq_file
198  */
199 typedef int (*lu_printer_t)(const struct lu_env *env,
200                             void *cookie, const char *format, ...)
201         __attribute__ ((format (printf, 3, 4)));
202
203 /**
204  * Operations specific for particular lu_object.
205  */
206 struct lu_object_operations {
207
208         /**
209          * Allocate lower-layer parts of the object by calling
210          * lu_device_operations::ldo_object_alloc() of the corresponding
211          * underlying device.
212          *
213          * This method is called once for each object inserted into object
214          * stack. It's responsibility of this method to insert lower-layer
215          * object(s) it create into appropriate places of object stack.
216          */
217         int (*loo_object_init)(const struct lu_env *env,
218                                struct lu_object *o,
219                                const struct lu_object_conf *conf);
220         /**
221          * Called (in top-to-bottom order) during object allocation after all
222          * layers were allocated and initialized. Can be used to perform
223          * initialization depending on lower layers.
224          */
225         int (*loo_object_start)(const struct lu_env *env,
226                                 struct lu_object *o);
227         /**
228          * Called before lu_object_operations::loo_object_free() to signal
229          * that object is being destroyed. Dual to
230          * lu_object_operations::loo_object_init().
231          */
232         void (*loo_object_delete)(const struct lu_env *env,
233                                   struct lu_object *o);
234         /**
235          * Dual to lu_device_operations::ldo_object_alloc(). Called when
236          * object is removed from memory.
237          */
238         void (*loo_object_free)(const struct lu_env *env,
239                                 struct lu_object *o);
240         /**
241          * Called when last active reference to the object is released (and
242          * object returns to the cache). This method is optional.
243          */
244         void (*loo_object_release)(const struct lu_env *env,
245                                    struct lu_object *o);
246         /**
247          * Optional debugging helper. Print given object.
248          */
249         int (*loo_object_print)(const struct lu_env *env, void *cookie,
250                                 lu_printer_t p, const struct lu_object *o);
251         /**
252          * Optional debugging method. Returns true iff method is internally
253          * consistent.
254          */
255         int (*loo_object_invariant)(const struct lu_object *o);
256 };
257
258 /**
259  * Type of lu_device.
260  */
261 struct lu_device_type;
262
263 /**
264  * Device: a layer in the server side abstraction stacking.
265  */
266 struct lu_device {
267         /**
268          * reference count. This is incremented, in particular, on each object
269          * created at this layer.
270          *
271          * \todo XXX which means that atomic_t is probably too small.
272          */
273         cfs_atomic_t                       ld_ref;
274         /**
275          * Pointer to device type. Never modified once set.
276          */
277         struct lu_device_type       *ld_type;
278         /**
279          * Operation vector for this device.
280          */
281         const struct lu_device_operations *ld_ops;
282         /**
283          * Stack this device belongs to.
284          */
285         struct lu_site                    *ld_site;
286         struct proc_dir_entry             *ld_proc_entry;
287
288         /** \todo XXX: temporary back pointer into obd. */
289         struct obd_device                 *ld_obd;
290         /**
291          * A list of references to this object, for debugging.
292          */
293         struct lu_ref                      ld_reference;
294         /**
295          * Link the device to the site.
296          **/
297         cfs_list_t                         ld_linkage;
298 };
299
300 struct lu_device_type_operations;
301
302 /**
303  * Tag bits for device type. They are used to distinguish certain groups of
304  * device types.
305  */
306 enum lu_device_tag {
307         /** this is meta-data device */
308         LU_DEVICE_MD = (1 << 0),
309         /** this is data device */
310         LU_DEVICE_DT = (1 << 1),
311         /** data device in the client stack */
312         LU_DEVICE_CL = (1 << 2)
313 };
314
315 /**
316  * Type of device.
317  */
318 struct lu_device_type {
319         /**
320          * Tag bits. Taken from enum lu_device_tag. Never modified once set.
321          */
322         __u32                                   ldt_tags;
323         /**
324          * Name of this class. Unique system-wide. Never modified once set.
325          */
326         char                                   *ldt_name;
327         /**
328          * Operations for this type.
329          */
330         const struct lu_device_type_operations *ldt_ops;
331         /**
332          * \todo XXX: temporary pointer to associated obd_type.
333          */
334         struct obd_type                        *ldt_obd_type;
335         /**
336          * \todo XXX: temporary: context tags used by obd_*() calls.
337          */
338         __u32                                   ldt_ctx_tags;
339         /**
340          * Number of existing device type instances.
341          */
342         unsigned                                ldt_device_nr;
343         /**
344          * Linkage into a global list of all device types.
345          *
346          * \see lu_device_types.
347          */
348         cfs_list_t                              ldt_linkage;
349 };
350
351 /**
352  * Operations on a device type.
353  */
354 struct lu_device_type_operations {
355         /**
356          * Allocate new device.
357          */
358         struct lu_device *(*ldto_device_alloc)(const struct lu_env *env,
359                                                struct lu_device_type *t,
360                                                struct lustre_cfg *lcfg);
361         /**
362          * Free device. Dual to
363          * lu_device_type_operations::ldto_device_alloc(). Returns pointer to
364          * the next device in the stack.
365          */
366         struct lu_device *(*ldto_device_free)(const struct lu_env *,
367                                               struct lu_device *);
368
369         /**
370          * Initialize the devices after allocation
371          */
372         int  (*ldto_device_init)(const struct lu_env *env,
373                                  struct lu_device *, const char *,
374                                  struct lu_device *);
375         /**
376          * Finalize device. Dual to
377          * lu_device_type_operations::ldto_device_init(). Returns pointer to
378          * the next device in the stack.
379          */
380         struct lu_device *(*ldto_device_fini)(const struct lu_env *env,
381                                               struct lu_device *);
382         /**
383          * Initialize device type. This is called on module load.
384          */
385         int  (*ldto_init)(struct lu_device_type *t);
386         /**
387          * Finalize device type. Dual to
388          * lu_device_type_operations::ldto_init(). Called on module unload.
389          */
390         void (*ldto_fini)(struct lu_device_type *t);
391         /**
392          * Called when the first device is created.
393          */
394         void (*ldto_start)(struct lu_device_type *t);
395         /**
396          * Called when number of devices drops to 0.
397          */
398         void (*ldto_stop)(struct lu_device_type *t);
399 };
400
401 /**
402  * Flags for the object layers.
403  */
404 enum lu_object_flags {
405         /**
406          * this flags is set if lu_object_operations::loo_object_init() has
407          * been called for this layer. Used by lu_object_alloc().
408          */
409         LU_OBJECT_ALLOCATED = (1 << 0)
410 };
411
412 /**
413  * Common object attributes.
414  */
415 struct lu_attr {
416         /** size in bytes */
417         __u64          la_size;
418         /** modification time in seconds since Epoch */
419         obd_time       la_mtime;
420         /** access time in seconds since Epoch */
421         obd_time       la_atime;
422         /** change time in seconds since Epoch */
423         obd_time       la_ctime;
424         /** 512-byte blocks allocated to object */
425         __u64          la_blocks;
426         /** permission bits and file type */
427         __u32          la_mode;
428         /** owner id */
429         __u32          la_uid;
430         /** group id */
431         __u32          la_gid;
432         /** object flags */
433         __u32          la_flags;
434         /** number of persistent references to this object */
435         __u32          la_nlink;
436         /** blk bits of the object*/
437         __u32          la_blkbits;
438         /** blk size of the object*/
439         __u32          la_blksize;
440         /** real device */
441         __u32          la_rdev;
442         /**
443          * valid bits
444          *
445          * \see enum la_valid
446          */
447         __u64          la_valid;
448 };
449
450 /** Bit-mask of valid attributes */
451 enum la_valid {
452         LA_ATIME = 1 << 0,
453         LA_MTIME = 1 << 1,
454         LA_CTIME = 1 << 2,
455         LA_SIZE  = 1 << 3,
456         LA_MODE  = 1 << 4,
457         LA_UID   = 1 << 5,
458         LA_GID   = 1 << 6,
459         LA_BLOCKS = 1 << 7,
460         LA_TYPE   = 1 << 8,
461         LA_FLAGS  = 1 << 9,
462         LA_NLINK  = 1 << 10,
463         LA_RDEV   = 1 << 11,
464         LA_BLKSIZE = 1 << 12,
465         LA_KILL_SUID = 1 << 13,
466         LA_KILL_SGID = 1 << 14,
467 };
468
469 /**
470  * Layer in the layered object.
471  */
472 struct lu_object {
473         /**
474          * Header for this object.
475          */
476         struct lu_object_header           *lo_header;
477         /**
478          * Device for this layer.
479          */
480         struct lu_device                  *lo_dev;
481         /**
482          * Operations for this object.
483          */
484         const struct lu_object_operations *lo_ops;
485         /**
486          * Linkage into list of all layers.
487          */
488         cfs_list_t                         lo_linkage;
489         /**
490          * Depth. Top level layer depth is 0.
491          */
492         int                                lo_depth;
493         /**
494          * Flags from enum lu_object_flags.
495          */
496         unsigned long                      lo_flags;
497         /**
498          * Link to the device, for debugging.
499          */
500         struct lu_ref_link                *lo_dev_ref;
501 };
502
503 enum lu_object_header_flags {
504         /**
505          * Don't keep this object in cache. Object will be destroyed as soon
506          * as last reference to it is released. This flag cannot be cleared
507          * once set.
508          */
509         LU_OBJECT_HEARD_BANSHEE = 0
510 };
511
512 enum lu_object_header_attr {
513         LOHA_EXISTS   = 1 << 0,
514         LOHA_REMOTE   = 1 << 1,
515         /**
516          * UNIX file type is stored in S_IFMT bits.
517          */
518         LOHA_FT_START = 001 << 12, /**< S_IFIFO */
519         LOHA_FT_END   = 017 << 12, /**< S_IFMT */
520 };
521
522 /**
523  * "Compound" object, consisting of multiple layers.
524  *
525  * Compound object with given fid is unique with given lu_site.
526  *
527  * Note, that object does *not* necessary correspond to the real object in the
528  * persistent storage: object is an anchor for locking and method calling, so
529  * it is created for things like not-yet-existing child created by mkdir or
530  * create calls. lu_object_operations::loo_exists() can be used to check
531  * whether object is backed by persistent storage entity.
532  */
533 struct lu_object_header {
534         /**
535          * Object flags from enum lu_object_header_flags. Set and checked
536          * atomically.
537          */
538         unsigned long          loh_flags;
539         /**
540          * Object reference count. Protected by lu_site::ls_guard.
541          */
542         cfs_atomic_t           loh_ref;
543         /**
544          * Fid, uniquely identifying this object.
545          */
546         struct lu_fid          loh_fid;
547         /**
548          * Common object attributes, cached for efficiency. From enum
549          * lu_object_header_attr.
550          */
551         __u32                  loh_attr;
552         /**
553          * Linkage into per-site hash table. Protected by lu_site::ls_guard.
554          */
555         cfs_hlist_node_t       loh_hash;
556         /**
557          * Linkage into per-site LRU list. Protected by lu_site::ls_guard.
558          */
559         cfs_list_t             loh_lru;
560         /**
561          * Linkage into list of layers. Never modified once set (except lately
562          * during object destruction). No locking is necessary.
563          */
564         cfs_list_t             loh_layers;
565         /**
566          * A list of references to this object, for debugging.
567          */
568         struct lu_ref          loh_reference;
569 };
570
571 struct fld;
572
573 struct lu_site_bkt_data {
574         /**
575          * number of busy object on this bucket
576          */
577         long                      lsb_busy;
578         /**
579          * LRU list, updated on each access to object. Protected by
580          * bucket lock of lu_site::ls_obj_hash.
581          *
582          * "Cold" end of LRU is lu_site::ls_lru.next. Accessed object are
583          * moved to the lu_site::ls_lru.prev (this is due to the non-existence
584          * of list_for_each_entry_safe_reverse()).
585          */
586         cfs_list_t                lsb_lru;
587         /**
588          * Wait-queue signaled when an object in this site is ultimately
589          * destroyed (lu_object_free()). It is used by lu_object_find() to
590          * wait before re-trying when object in the process of destruction is
591          * found in the hash table.
592          *
593          * \see htable_lookup().
594          */
595         cfs_waitq_t               lsb_marche_funebre;
596 };
597
598 enum {
599         LU_SS_CREATED         = 0,
600         LU_SS_CACHE_HIT,
601         LU_SS_CACHE_MISS,
602         LU_SS_CACHE_RACE,
603         LU_SS_CACHE_DEATH_RACE,
604         LU_SS_LRU_PURGED,
605         LU_SS_LAST_STAT
606 };
607
608 /**
609  * lu_site is a "compartment" within which objects are unique, and LRU
610  * discipline is maintained.
611  *
612  * lu_site exists so that multiple layered stacks can co-exist in the same
613  * address space.
614  *
615  * lu_site has the same relation to lu_device as lu_object_header to
616  * lu_object.
617  */
618 struct lu_site {
619         /**
620          * objects hash table
621          */
622         cfs_hash_t               *ls_obj_hash;
623         /**
624          * index of bucket on hash table while purging
625          */
626         int                       ls_purge_start;
627         /**
628          * Top-level device for this stack.
629          */
630         struct lu_device         *ls_top_dev;
631         /**
632          * Bottom-level device for this stack
633          */
634         struct lu_device        *ls_bottom_dev;
635         /**
636          * Linkage into global list of sites.
637          */
638         cfs_list_t                ls_linkage;
639         /**
640          * List for lu device for this site, protected
641          * by ls_ld_lock.
642          **/
643         cfs_list_t                ls_ld_linkage;
644         spinlock_t              ls_ld_lock;
645
646         /**
647          * lu_site stats
648          */
649         struct lprocfs_stats    *ls_stats;
650         struct lprocfs_stats    *ls_time_stats;
651         /**
652          * XXX: a hack! fld has to find md_site via site, remove when possible
653          */
654         struct md_site          *ld_md_site;
655 };
656
657 static inline struct lu_site_bkt_data *
658 lu_site_bkt_from_fid(struct lu_site *site, struct lu_fid *fid)
659 {
660         cfs_hash_bd_t bd;
661
662         cfs_hash_bd_get(site->ls_obj_hash, fid, &bd);
663         return cfs_hash_bd_extra_get(site->ls_obj_hash, &bd);
664 }
665
666 /** \name ctors
667  * Constructors/destructors.
668  * @{
669  */
670
671 int  lu_site_init         (struct lu_site *s, struct lu_device *d);
672 void lu_site_fini         (struct lu_site *s);
673 int  lu_site_init_finish  (struct lu_site *s);
674 void lu_stack_fini        (const struct lu_env *env, struct lu_device *top);
675 void lu_device_get        (struct lu_device *d);
676 void lu_device_put        (struct lu_device *d);
677 int  lu_device_init       (struct lu_device *d, struct lu_device_type *t);
678 void lu_device_fini       (struct lu_device *d);
679 int  lu_object_header_init(struct lu_object_header *h);
680 void lu_object_header_fini(struct lu_object_header *h);
681 int  lu_object_init       (struct lu_object *o,
682                            struct lu_object_header *h, struct lu_device *d);
683 void lu_object_fini       (struct lu_object *o);
684 void lu_object_add_top    (struct lu_object_header *h, struct lu_object *o);
685 void lu_object_add        (struct lu_object *before, struct lu_object *o);
686
687 void lu_dev_add_linkage(struct lu_site *s, struct lu_device *d);
688 void lu_dev_del_linkage(struct lu_site *s, struct lu_device *d);
689
690 /**
691  * Helpers to initialize and finalize device types.
692  */
693
694 int  lu_device_type_init(struct lu_device_type *ldt);
695 void lu_device_type_fini(struct lu_device_type *ldt);
696 void lu_types_stop(void);
697
698 /** @} ctors */
699
700 /** \name caching
701  * Caching and reference counting.
702  * @{
703  */
704
705 /**
706  * Acquire additional reference to the given object. This function is used to
707  * attain additional reference. To acquire initial reference use
708  * lu_object_find().
709  */
710 static inline void lu_object_get(struct lu_object *o)
711 {
712         LASSERT(cfs_atomic_read(&o->lo_header->loh_ref) > 0);
713         cfs_atomic_inc(&o->lo_header->loh_ref);
714 }
715
716 /**
717  * Return true of object will not be cached after last reference to it is
718  * released.
719  */
720 static inline int lu_object_is_dying(const struct lu_object_header *h)
721 {
722         return test_bit(LU_OBJECT_HEARD_BANSHEE, &h->loh_flags);
723 }
724
725 void lu_object_put(const struct lu_env *env, struct lu_object *o);
726 void lu_object_put_nocache(const struct lu_env *env, struct lu_object *o);
727
728 int lu_site_purge(const struct lu_env *env, struct lu_site *s, int nr);
729
730 void lu_site_print(const struct lu_env *env, struct lu_site *s, void *cookie,
731                    lu_printer_t printer);
732 struct lu_object *lu_object_find(const struct lu_env *env,
733                                  struct lu_device *dev, const struct lu_fid *f,
734                                  const struct lu_object_conf *conf);
735 struct lu_object *lu_object_find_at(const struct lu_env *env,
736                                     struct lu_device *dev,
737                                     const struct lu_fid *f,
738                                     const struct lu_object_conf *conf);
739 struct lu_object *lu_object_find_slice(const struct lu_env *env,
740                                        struct lu_device *dev,
741                                        const struct lu_fid *f,
742                                        const struct lu_object_conf *conf);
743 /** @} caching */
744
745 /** \name helpers
746  * Helpers.
747  * @{
748  */
749
750 /**
751  * First (topmost) sub-object of given compound object
752  */
753 static inline struct lu_object *lu_object_top(struct lu_object_header *h)
754 {
755         LASSERT(!cfs_list_empty(&h->loh_layers));
756         return container_of0(h->loh_layers.next, struct lu_object, lo_linkage);
757 }
758
759 /**
760  * Next sub-object in the layering
761  */
762 static inline struct lu_object *lu_object_next(const struct lu_object *o)
763 {
764         return container_of0(o->lo_linkage.next, struct lu_object, lo_linkage);
765 }
766
767 /**
768  * Pointer to the fid of this object.
769  */
770 static inline const struct lu_fid *lu_object_fid(const struct lu_object *o)
771 {
772         return &o->lo_header->loh_fid;
773 }
774
775 /**
776  * return device operations vector for this object
777  */
778 static const inline struct lu_device_operations *
779 lu_object_ops(const struct lu_object *o)
780 {
781         return o->lo_dev->ld_ops;
782 }
783
784 /**
785  * Given a compound object, find its slice, corresponding to the device type
786  * \a dtype.
787  */
788 struct lu_object *lu_object_locate(struct lu_object_header *h,
789                                    const struct lu_device_type *dtype);
790
791 /**
792  * Printer function emitting messages through libcfs_debug_msg().
793  */
794 int lu_cdebug_printer(const struct lu_env *env,
795                       void *cookie, const char *format, ...);
796
797 /**
798  * Print object description followed by a user-supplied message.
799  */
800 #define LU_OBJECT_DEBUG(mask, env, object, format, ...)                   \
801 do {                                                                      \
802         LIBCFS_DEBUG_MSG_DATA_DECL(msgdata, mask, NULL);                  \
803                                                                           \
804         if (cfs_cdebug_show(mask, DEBUG_SUBSYSTEM)) {                     \
805                 lu_object_print(env, &msgdata, lu_cdebug_printer, object);\
806                 CDEBUG(mask, format , ## __VA_ARGS__);                    \
807         }                                                                 \
808 } while (0)
809
810 /**
811  * Print short object description followed by a user-supplied message.
812  */
813 #define LU_OBJECT_HEADER(mask, env, object, format, ...)                \
814 do {                                                                    \
815         LIBCFS_DEBUG_MSG_DATA_DECL(msgdata, mask, NULL);                \
816                                                                         \
817         if (cfs_cdebug_show(mask, DEBUG_SUBSYSTEM)) {                   \
818                 lu_object_header_print(env, &msgdata, lu_cdebug_printer,\
819                                        (object)->lo_header);            \
820                 lu_cdebug_printer(env, &msgdata, "\n");                 \
821                 CDEBUG(mask, format , ## __VA_ARGS__);                  \
822         }                                                               \
823 } while (0)
824
825 void lu_object_print       (const struct lu_env *env, void *cookie,
826                             lu_printer_t printer, const struct lu_object *o);
827 void lu_object_header_print(const struct lu_env *env, void *cookie,
828                             lu_printer_t printer,
829                             const struct lu_object_header *hdr);
830
831 /**
832  * Check object consistency.
833  */
834 int lu_object_invariant(const struct lu_object *o);
835
836
837 /**
838  * \retval  1 iff object \a o exists on stable storage,
839  * \retval  0 iff object \a o not exists on stable storage.
840  * \retval -1 iff object \a o is on remote server.
841  */
842 static inline int lu_object_exists(const struct lu_object *o)
843 {
844         __u32 attr;
845
846         attr = o->lo_header->loh_attr;
847         if (attr & LOHA_REMOTE)
848                 return -1;
849         else if (attr & LOHA_EXISTS)
850                 return +1;
851         else
852                 return 0;
853 }
854
855 static inline int lu_object_assert_exists(const struct lu_object *o)
856 {
857         return lu_object_exists(o) != 0;
858 }
859
860 static inline int lu_object_assert_not_exists(const struct lu_object *o)
861 {
862         return lu_object_exists(o) <= 0;
863 }
864
865 /**
866  * Attr of this object.
867  */
868 static inline __u32 lu_object_attr(const struct lu_object *o)
869 {
870         LASSERT(lu_object_exists(o) > 0);
871         return o->lo_header->loh_attr;
872 }
873
874 static inline struct lu_ref_link *lu_object_ref_add(struct lu_object *o,
875                                                     const char *scope,
876                                                     const void *source)
877 {
878         return lu_ref_add(&o->lo_header->loh_reference, scope, source);
879 }
880
881 static inline void lu_object_ref_del(struct lu_object *o,
882                                      const char *scope, const void *source)
883 {
884         lu_ref_del(&o->lo_header->loh_reference, scope, source);
885 }
886
887 static inline void lu_object_ref_del_at(struct lu_object *o,
888                                         struct lu_ref_link *link,
889                                         const char *scope, const void *source)
890 {
891         lu_ref_del_at(&o->lo_header->loh_reference, link, scope, source);
892 }
893
894 /** input params, should be filled out by mdt */
895 struct lu_rdpg {
896         /** hash */
897         __u64                   rp_hash;
898         /** count in bytes */
899         unsigned int            rp_count;
900         /** number of pages */
901         unsigned int            rp_npages;
902         /** requested attr */
903         __u32                   rp_attrs;
904         /** pointers to pages */
905         struct page           **rp_pages;
906 };
907
908 enum lu_xattr_flags {
909         LU_XATTR_REPLACE = (1 << 0),
910         LU_XATTR_CREATE  = (1 << 1)
911 };
912
913 /** @} helpers */
914
915 /** \name lu_context
916  * @{ */
917
918 /** For lu_context health-checks */
919 enum lu_context_state {
920         LCS_INITIALIZED = 1,
921         LCS_ENTERED,
922         LCS_LEFT,
923         LCS_FINALIZED
924 };
925
926 /**
927  * lu_context. Execution context for lu_object methods. Currently associated
928  * with thread.
929  *
930  * All lu_object methods, except device and device type methods (called during
931  * system initialization and shutdown) are executed "within" some
932  * lu_context. This means, that pointer to some "current" lu_context is passed
933  * as an argument to all methods.
934  *
935  * All service ptlrpc threads create lu_context as part of their
936  * initialization. It is possible to create "stand-alone" context for other
937  * execution environments (like system calls).
938  *
939  * lu_object methods mainly use lu_context through lu_context_key interface
940  * that allows each layer to associate arbitrary pieces of data with each
941  * context (see pthread_key_create(3) for similar interface).
942  *
943  * On a client, lu_context is bound to a thread, see cl_env_get().
944  *
945  * \see lu_context_key
946  */
947 struct lu_context {
948         /**
949          * lu_context is used on the client side too. Yet we don't want to
950          * allocate values of server-side keys for the client contexts and
951          * vice versa.
952          *
953          * To achieve this, set of tags in introduced. Contexts and keys are
954          * marked with tags. Key value are created only for context whose set
955          * of tags has non-empty intersection with one for key. Tags are taken
956          * from enum lu_context_tag.
957          */
958         __u32                  lc_tags;
959         enum lu_context_state  lc_state;
960         /**
961          * Pointer to the home service thread. NULL for other execution
962          * contexts.
963          */
964         struct ptlrpc_thread  *lc_thread;
965         /**
966          * Pointer to an array with key values. Internal implementation
967          * detail.
968          */
969         void                 **lc_value;
970         /**
971          * Linkage into a list of all remembered contexts. Only
972          * `non-transient' contexts, i.e., ones created for service threads
973          * are placed here.
974          */
975         cfs_list_t             lc_remember;
976         /**
977          * Version counter used to skip calls to lu_context_refill() when no
978          * keys were registered.
979          */
980         unsigned               lc_version;
981         /**
982          * Debugging cookie.
983          */
984         unsigned               lc_cookie;
985 };
986
987 /**
988  * lu_context_key interface. Similar to pthread_key.
989  */
990
991 enum lu_context_tag {
992         /**
993          * Thread on md server
994          */
995         LCT_MD_THREAD = 1 << 0,
996         /**
997          * Thread on dt server
998          */
999         LCT_DT_THREAD = 1 << 1,
1000         /**
1001          * Context for transaction handle
1002          */
1003         LCT_TX_HANDLE = 1 << 2,
1004         /**
1005          * Thread on client
1006          */
1007         LCT_CL_THREAD = 1 << 3,
1008         /**
1009          * A per-request session on a server, and a per-system-call session on
1010          * a client.
1011          */
1012         LCT_SESSION   = 1 << 4,
1013         /**
1014          * A per-request data on OSP device
1015          */
1016         LCT_OSP_THREAD = 1 << 5,
1017         /**
1018          * MGS device thread
1019          */
1020         LCT_MG_THREAD = 1 << 6,
1021         /**
1022          * Context for local operations
1023          */
1024         LCT_LOCAL = 1 << 7,
1025         /**
1026          * Set when at least one of keys, having values in this context has
1027          * non-NULL lu_context_key::lct_exit() method. This is used to
1028          * optimize lu_context_exit() call.
1029          */
1030         LCT_HAS_EXIT  = 1 << 28,
1031         /**
1032          * Don't add references for modules creating key values in that context.
1033          * This is only for contexts used internally by lu_object framework.
1034          */
1035         LCT_NOREF     = 1 << 29,
1036         /**
1037          * Key is being prepared for retiring, don't create new values for it.
1038          */
1039         LCT_QUIESCENT = 1 << 30,
1040         /**
1041          * Context should be remembered.
1042          */
1043         LCT_REMEMBER  = 1 << 31,
1044         /**
1045          * Contexts usable in cache shrinker thread.
1046          */
1047         LCT_SHRINKER  = LCT_MD_THREAD|LCT_DT_THREAD|LCT_CL_THREAD|LCT_NOREF
1048 };
1049
1050 /**
1051  * Key. Represents per-context value slot.
1052  *
1053  * Keys are usually registered when module owning the key is initialized, and
1054  * de-registered when module is unloaded. Once key is registered, all new
1055  * contexts with matching tags, will get key value. "Old" contexts, already
1056  * initialized at the time of key registration, can be forced to get key value
1057  * by calling lu_context_refill().
1058  *
1059  * Every key value is counted in lu_context_key::lct_used and acquires a
1060  * reference on an owning module. This means, that all key values have to be
1061  * destroyed before module can be unloaded. This is usually achieved by
1062  * stopping threads started by the module, that created contexts in their
1063  * entry functions. Situation is complicated by the threads shared by multiple
1064  * modules, like ptlrpcd daemon on a client. To work around this problem,
1065  * contexts, created in such threads, are `remembered' (see
1066  * LCT_REMEMBER)---i.e., added into a global list. When module is preparing
1067  * for unloading it does the following:
1068  *
1069  *     - marks its keys as `quiescent' (lu_context_tag::LCT_QUIESCENT)
1070  *       preventing new key values from being allocated in the new contexts,
1071  *       and
1072  *
1073  *     - scans a list of remembered contexts, destroying values of module
1074  *       keys, thus releasing references to the module.
1075  *
1076  * This is done by lu_context_key_quiesce(). If module is re-activated
1077  * before key has been de-registered, lu_context_key_revive() call clears
1078  * `quiescent' marker.
1079  *
1080  * lu_context code doesn't provide any internal synchronization for these
1081  * activities---it's assumed that startup (including threads start-up) and
1082  * shutdown are serialized by some external means.
1083  *
1084  * \see lu_context
1085  */
1086 struct lu_context_key {
1087         /**
1088          * Set of tags for which values of this key are to be instantiated.
1089          */
1090         __u32 lct_tags;
1091         /**
1092          * Value constructor. This is called when new value is created for a
1093          * context. Returns pointer to new value of error pointer.
1094          */
1095         void  *(*lct_init)(const struct lu_context *ctx,
1096                            struct lu_context_key *key);
1097         /**
1098          * Value destructor. Called when context with previously allocated
1099          * value of this slot is destroyed. \a data is a value that was returned
1100          * by a matching call to lu_context_key::lct_init().
1101          */
1102         void   (*lct_fini)(const struct lu_context *ctx,
1103                            struct lu_context_key *key, void *data);
1104         /**
1105          * Optional method called on lu_context_exit() for all allocated
1106          * keys. Can be used by debugging code checking that locks are
1107          * released, etc.
1108          */
1109         void   (*lct_exit)(const struct lu_context *ctx,
1110                            struct lu_context_key *key, void *data);
1111         /**
1112          * Internal implementation detail: index within lu_context::lc_value[]
1113          * reserved for this key.
1114          */
1115         int      lct_index;
1116         /**
1117          * Internal implementation detail: number of values created for this
1118          * key.
1119          */
1120         cfs_atomic_t lct_used;
1121         /**
1122          * Internal implementation detail: module for this key.
1123          */
1124         cfs_module_t *lct_owner;
1125         /**
1126          * References to this key. For debugging.
1127          */
1128         struct lu_ref  lct_reference;
1129 };
1130
1131 #define LU_KEY_INIT(mod, type)                                    \
1132         static void* mod##_key_init(const struct lu_context *ctx, \
1133                                     struct lu_context_key *key)   \
1134         {                                                         \
1135                 type *value;                                      \
1136                                                                   \
1137                 CLASSERT(CFS_PAGE_SIZE >= sizeof (*value));       \
1138                                                                   \
1139                 OBD_ALLOC_PTR(value);                             \
1140                 if (value == NULL)                                \
1141                         value = ERR_PTR(-ENOMEM);                 \
1142                                                                   \
1143                 return value;                                     \
1144         }                                                         \
1145         struct __##mod##__dummy_init {;} /* semicolon catcher */
1146
1147 #define LU_KEY_FINI(mod, type)                                              \
1148         static void mod##_key_fini(const struct lu_context *ctx,            \
1149                                     struct lu_context_key *key, void* data) \
1150         {                                                                   \
1151                 type *info = data;                                          \
1152                                                                             \
1153                 OBD_FREE_PTR(info);                                         \
1154         }                                                                   \
1155         struct __##mod##__dummy_fini {;} /* semicolon catcher */
1156
1157 #define LU_KEY_INIT_FINI(mod, type)   \
1158         LU_KEY_INIT(mod,type);        \
1159         LU_KEY_FINI(mod,type)
1160
1161 #define LU_CONTEXT_KEY_DEFINE(mod, tags)                \
1162         struct lu_context_key mod##_thread_key = {      \
1163                 .lct_tags = tags,                       \
1164                 .lct_init = mod##_key_init,             \
1165                 .lct_fini = mod##_key_fini              \
1166         }
1167
1168 #define LU_CONTEXT_KEY_INIT(key)                        \
1169 do {                                                    \
1170         (key)->lct_owner = THIS_MODULE;                 \
1171 } while (0)
1172
1173 int   lu_context_key_register(struct lu_context_key *key);
1174 void  lu_context_key_degister(struct lu_context_key *key);
1175 void *lu_context_key_get     (const struct lu_context *ctx,
1176                                const struct lu_context_key *key);
1177 void  lu_context_key_quiesce (struct lu_context_key *key);
1178 void  lu_context_key_revive  (struct lu_context_key *key);
1179
1180
1181 /*
1182  * LU_KEY_INIT_GENERIC() has to be a macro to correctly determine an
1183  * owning module.
1184  */
1185
1186 #define LU_KEY_INIT_GENERIC(mod)                                        \
1187         static void mod##_key_init_generic(struct lu_context_key *k, ...) \
1188         {                                                               \
1189                 struct lu_context_key *key = k;                         \
1190                 va_list args;                                           \
1191                                                                         \
1192                 va_start(args, k);                                      \
1193                 do {                                                    \
1194                         LU_CONTEXT_KEY_INIT(key);                       \
1195                         key = va_arg(args, struct lu_context_key *);    \
1196                 } while (key != NULL);                                  \
1197                 va_end(args);                                           \
1198         }
1199
1200 #define LU_TYPE_INIT(mod, ...)                                          \
1201         LU_KEY_INIT_GENERIC(mod)                                        \
1202         static int mod##_type_init(struct lu_device_type *t)            \
1203         {                                                               \
1204                 mod##_key_init_generic(__VA_ARGS__, NULL);              \
1205                 return lu_context_key_register_many(__VA_ARGS__, NULL); \
1206         }                                                               \
1207         struct __##mod##_dummy_type_init {;}
1208
1209 #define LU_TYPE_FINI(mod, ...)                                          \
1210         static void mod##_type_fini(struct lu_device_type *t)           \
1211         {                                                               \
1212                 lu_context_key_degister_many(__VA_ARGS__, NULL);        \
1213         }                                                               \
1214         struct __##mod##_dummy_type_fini {;}
1215
1216 #define LU_TYPE_START(mod, ...)                                 \
1217         static void mod##_type_start(struct lu_device_type *t)  \
1218         {                                                       \
1219                 lu_context_key_revive_many(__VA_ARGS__, NULL);  \
1220         }                                                       \
1221         struct __##mod##_dummy_type_start {;}
1222
1223 #define LU_TYPE_STOP(mod, ...)                                  \
1224         static void mod##_type_stop(struct lu_device_type *t)   \
1225         {                                                       \
1226                 lu_context_key_quiesce_many(__VA_ARGS__, NULL); \
1227         }                                                       \
1228         struct __##mod##_dummy_type_stop {;}
1229
1230
1231
1232 #define LU_TYPE_INIT_FINI(mod, ...)             \
1233         LU_TYPE_INIT(mod, __VA_ARGS__);         \
1234         LU_TYPE_FINI(mod, __VA_ARGS__);         \
1235         LU_TYPE_START(mod, __VA_ARGS__);        \
1236         LU_TYPE_STOP(mod, __VA_ARGS__)
1237
1238 int   lu_context_init  (struct lu_context *ctx, __u32 tags);
1239 void  lu_context_fini  (struct lu_context *ctx);
1240 void  lu_context_enter (struct lu_context *ctx);
1241 void  lu_context_exit  (struct lu_context *ctx);
1242 int   lu_context_refill(struct lu_context *ctx);
1243
1244 /*
1245  * Helper functions to operate on multiple keys. These are used by the default
1246  * device type operations, defined by LU_TYPE_INIT_FINI().
1247  */
1248
1249 int  lu_context_key_register_many(struct lu_context_key *k, ...);
1250 void lu_context_key_degister_many(struct lu_context_key *k, ...);
1251 void lu_context_key_revive_many  (struct lu_context_key *k, ...);
1252 void lu_context_key_quiesce_many (struct lu_context_key *k, ...);
1253
1254 /*
1255  * update/clear ctx/ses tags.
1256  */
1257 void lu_context_tags_update(__u32 tags);
1258 void lu_context_tags_clear(__u32 tags);
1259 void lu_session_tags_update(__u32 tags);
1260 void lu_session_tags_clear(__u32 tags);
1261
1262 /**
1263  * Environment.
1264  */
1265 struct lu_env {
1266         /**
1267          * "Local" context, used to store data instead of stack.
1268          */
1269         struct lu_context  le_ctx;
1270         /**
1271          * "Session" context for per-request data.
1272          */
1273         struct lu_context *le_ses;
1274 };
1275
1276 int  lu_env_init  (struct lu_env *env, __u32 tags);
1277 void lu_env_fini  (struct lu_env *env);
1278 int  lu_env_refill(struct lu_env *env);
1279 int  lu_env_refill_by_tags(struct lu_env *env, __u32 ctags, __u32 stags);
1280
1281 /** @} lu_context */
1282
1283 /**
1284  * Output site statistical counters into a buffer. Suitable for
1285  * ll_rd_*()-style functions.
1286  */
1287 int lu_site_stats_print(const struct lu_site *s, char *page, int count);
1288
1289 /**
1290  * Common name structure to be passed around for various name related methods.
1291  */
1292 struct lu_name {
1293         const char    *ln_name;
1294         int            ln_namelen;
1295 };
1296
1297 /**
1298  * Common buffer structure to be passed around for various xattr_{s,g}et()
1299  * methods.
1300  */
1301 struct lu_buf {
1302         void   *lb_buf;
1303         ssize_t lb_len;
1304 };
1305
1306 /** null buffer */
1307 extern struct lu_buf LU_BUF_NULL;
1308
1309 #define DLUBUF "(%p %zu)"
1310 #define PLUBUF(buf) (buf)->lb_buf, (buf)->lb_len
1311 /**
1312  * One-time initializers, called at obdclass module initialization, not
1313  * exported.
1314  */
1315
1316 /**
1317  * Initialization of global lu_* data.
1318  */
1319 int lu_global_init(void);
1320
1321 /**
1322  * Dual to lu_global_init().
1323  */
1324 void lu_global_fini(void);
1325
1326 enum {
1327         LU_TIME_FIND_LOOKUP,
1328         LU_TIME_FIND_ALLOC,
1329         LU_TIME_FIND_INSERT,
1330         LU_TIME_NR
1331 };
1332
1333 extern const char *lu_time_names[LU_TIME_NR];
1334
1335 struct lu_kmem_descr {
1336         cfs_mem_cache_t **ckd_cache;
1337         const char       *ckd_name;
1338         const size_t      ckd_size;
1339 };
1340
1341 int  lu_kmem_init(struct lu_kmem_descr *caches);
1342 void lu_kmem_fini(struct lu_kmem_descr *caches);
1343
1344 void lu_object_assign_fid(const struct lu_env *env, struct lu_object *o,
1345                           const struct lu_fid *fid);
1346 struct lu_object *lu_object_anon(const struct lu_env *env,
1347                                  struct lu_device *dev,
1348                                  const struct lu_object_conf *conf);
1349
1350 /** @} lu */
1351 #endif /* __LUSTRE_LU_OBJECT_H */