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