Whamcloud - gitweb
f50fee7b7e8898a014ced98a47025121fdf0e001
[fs/lustre-release.git] / lustre / include / cl_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) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
28  * Use is subject to license terms.
29  *
30  * Copyright (c) 2011, 2015, 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 #ifndef _LUSTRE_CL_OBJECT_H
37 #define _LUSTRE_CL_OBJECT_H
38
39 /** \defgroup clio clio
40  *
41  * Client objects implement io operations and cache pages.
42  *
43  * Examples: lov and osc are implementations of cl interface.
44  *
45  * Big Theory Statement.
46  *
47  * Layered objects.
48  *
49  * Client implementation is based on the following data-types:
50  *
51  *   - cl_object
52  *
53  *   - cl_page
54  *
55  *   - cl_lock     represents an extent lock on an object.
56  *
57  *   - cl_io       represents high-level i/o activity such as whole read/write
58  *                 system call, or write-out of pages from under the lock being
59  *                 canceled. cl_io has sub-ios that can be stopped and resumed
60  *                 independently, thus achieving high degree of transfer
61  *                 parallelism. Single cl_io can be advanced forward by
62  *                 the multiple threads (although in the most usual case of
63  *                 read/write system call it is associated with the single user
64  *                 thread, that issued the system call).
65  *
66  * Terminology
67  *
68  *     - to avoid confusion high-level I/O operation like read or write system
69  *     call is referred to as "an io", whereas low-level I/O operation, like
70  *     RPC, is referred to as "a transfer"
71  *
72  *     - "generic code" means generic (not file system specific) code in the
73  *     hosting environment. "cl-code" means code (mostly in cl_*.c files) that
74  *     is not layer specific.
75  *
76  * Locking.
77  *
78  *  - i_mutex
79  *      - PG_locked
80  *          - cl_object_header::coh_page_guard
81  *          - lu_site::ls_guard
82  *
83  * See the top comment in cl_object.c for the description of overall locking and
84  * reference-counting design.
85  *
86  * See comments below for the description of i/o, page, and dlm-locking
87  * design.
88  *
89  * @{
90  */
91
92 /*
93  * super-class definitions.
94  */
95 #include <libcfs/libcfs.h>
96 #include <lu_object.h>
97 #include <linux/atomic.h>
98 #include <linux/mutex.h>
99 #include <linux/radix-tree.h>
100 #include <linux/spinlock.h>
101 #include <linux/wait.h>
102 #include <lustre_dlm.h>
103
104 struct obd_info;
105 struct inode;
106
107 struct cl_device;
108
109 struct cl_object;
110
111 struct cl_page;
112 struct cl_page_slice;
113 struct cl_lock;
114 struct cl_lock_slice;
115
116 struct cl_lock_operations;
117 struct cl_page_operations;
118
119 struct cl_io;
120 struct cl_io_slice;
121
122 struct cl_req_attr;
123
124 /**
125  * Device in the client stack.
126  *
127  * \see vvp_device, lov_device, lovsub_device, osc_device
128  */
129 struct cl_device {
130         /** Super-class. */
131         struct lu_device                   cd_lu_dev;
132 };
133
134 /** \addtogroup cl_object cl_object
135  * @{ */
136 /**
137  * "Data attributes" of cl_object. Data attributes can be updated
138  * independently for a sub-object, and top-object's attributes are calculated
139  * from sub-objects' ones.
140  */
141 struct cl_attr {
142         /** Object size, in bytes */
143         loff_t cat_size;
144         /**
145          * Known minimal size, in bytes.
146          *
147          * This is only valid when at least one DLM lock is held.
148          */
149         loff_t cat_kms;
150         /** Modification time. Measured in seconds since epoch. */
151         time_t cat_mtime;
152         /** Access time. Measured in seconds since epoch. */
153         time_t cat_atime;
154         /** Change time. Measured in seconds since epoch. */
155         time_t cat_ctime;
156         /**
157          * Blocks allocated to this cl_object on the server file system.
158          *
159          * \todo XXX An interface for block size is needed.
160          */
161         __u64  cat_blocks;
162         /**
163          * User identifier for quota purposes.
164          */
165         uid_t  cat_uid;
166         /**
167          * Group identifier for quota purposes.
168          */
169         gid_t  cat_gid;
170
171         /* nlink of the directory */
172         __u64  cat_nlink;
173 };
174
175 /**
176  * Fields in cl_attr that are being set.
177  */
178 enum cl_attr_valid {
179         CAT_SIZE   = 1 << 0,
180         CAT_KMS    = 1 << 1,
181         CAT_MTIME  = 1 << 3,
182         CAT_ATIME  = 1 << 4,
183         CAT_CTIME  = 1 << 5,
184         CAT_BLOCKS = 1 << 6,
185         CAT_UID    = 1 << 7,
186         CAT_GID    = 1 << 8
187 };
188
189 /**
190  * Sub-class of lu_object with methods common for objects on the client
191  * stacks.
192  *
193  * cl_object: represents a regular file system object, both a file and a
194  *    stripe. cl_object is based on lu_object: it is identified by a fid,
195  *    layered, cached, hashed, and lrued. Important distinction with the server
196  *    side, where md_object and dt_object are used, is that cl_object "fans out"
197  *    at the lov/sns level: depending on the file layout, single file is
198  *    represented as a set of "sub-objects" (stripes). At the implementation
199  *    level, struct lov_object contains an array of cl_objects. Each sub-object
200  *    is a full-fledged cl_object, having its fid, living in the lru and hash
201  *    table.
202  *
203  *    This leads to the next important difference with the server side: on the
204  *    client, it's quite usual to have objects with the different sequence of
205  *    layers. For example, typical top-object is composed of the following
206  *    layers:
207  *
208  *        - vvp
209  *        - lov
210  *
211  *    whereas its sub-objects are composed of
212  *
213  *        - lovsub
214  *        - osc
215  *
216  *    layers. Here "lovsub" is a mostly dummy layer, whose purpose is to keep
217  *    track of the object-subobject relationship.
218  *
219  *    Sub-objects are not cached independently: when top-object is about to
220  *    be discarded from the memory, all its sub-objects are torn-down and
221  *    destroyed too.
222  *
223  * \see vvp_object, lov_object, lovsub_object, osc_object
224  */
225 struct cl_object {
226         /** super class */
227         struct lu_object                   co_lu;
228         /** per-object-layer operations */
229         const struct cl_object_operations *co_ops;
230         /** offset of page slice in cl_page buffer */
231         int                                co_slice_off;
232 };
233
234 /**
235  * Description of the client object configuration. This is used for the
236  * creation of a new client object that is identified by a more state than
237  * fid.
238  */
239 struct cl_object_conf {
240         /** Super-class. */
241         struct lu_object_conf     coc_lu;
242         union {
243                 /**
244                  * Object layout. This is consumed by lov.
245                  */
246                 struct lu_buf    coc_layout;
247                 /**
248                  * Description of particular stripe location in the
249                  * cluster. This is consumed by osc.
250                  */
251                 struct lov_oinfo *coc_oinfo;
252         } u;
253         /**
254          * VFS inode. This is consumed by vvp.
255          */
256         struct inode             *coc_inode;
257         /**
258          * Layout lock handle.
259          */
260         struct ldlm_lock         *coc_lock;
261         /**
262          * Operation to handle layout, OBJECT_CONF_XYZ.
263          */
264         int                       coc_opc;
265 };
266
267 enum {
268         /** configure layout, set up a new stripe, must be called while
269          * holding layout lock. */
270         OBJECT_CONF_SET = 0,
271         /** invalidate the current stripe configuration due to losing
272          * layout lock. */
273         OBJECT_CONF_INVALIDATE = 1,
274         /** wait for old layout to go away so that new layout can be
275          * set up. */
276         OBJECT_CONF_WAIT = 2
277 };
278
279 enum {
280         CL_LAYOUT_GEN_NONE      = (u32)-2,      /* layout lock was cancelled */
281         CL_LAYOUT_GEN_EMPTY     = (u32)-1,      /* for empty layout */
282 };
283
284 struct cl_layout {
285         /** the buffer to return the layout in lov_mds_md format. */
286         struct lu_buf   cl_buf;
287         /** size of layout in lov_mds_md format. */
288         size_t          cl_size;
289         /** Layout generation. */
290         u32             cl_layout_gen;
291 };
292
293 /**
294  * Operations implemented for each cl object layer.
295  *
296  * \see vvp_ops, lov_ops, lovsub_ops, osc_ops
297  */
298 struct cl_object_operations {
299         /**
300          * Initialize page slice for this layer. Called top-to-bottom through
301          * every object layer when a new cl_page is instantiated. Layer
302          * keeping private per-page data, or requiring its own page operations
303          * vector should allocate these data here, and attach then to the page
304          * by calling cl_page_slice_add(). \a vmpage is locked (in the VM
305          * sense). Optional.
306          *
307          * \retval NULL success.
308          *
309          * \retval ERR_PTR(errno) failure code.
310          *
311          * \retval valid-pointer pointer to already existing referenced page
312          *         to be used instead of newly created.
313          */
314         int  (*coo_page_init)(const struct lu_env *env, struct cl_object *obj,
315                                 struct cl_page *page, pgoff_t index);
316         /**
317          * Initialize lock slice for this layer. Called top-to-bottom through
318          * every object layer when a new cl_lock is instantiated. Layer
319          * keeping private per-lock data, or requiring its own lock operations
320          * vector should allocate these data here, and attach then to the lock
321          * by calling cl_lock_slice_add(). Mandatory.
322          */
323         int  (*coo_lock_init)(const struct lu_env *env,
324                               struct cl_object *obj, struct cl_lock *lock,
325                               const struct cl_io *io);
326         /**
327          * Initialize io state for a given layer.
328          *
329          * called top-to-bottom once per io existence to initialize io
330          * state. If layer wants to keep some state for this type of io, it
331          * has to embed struct cl_io_slice in lu_env::le_ses, and register
332          * slice with cl_io_slice_add(). It is guaranteed that all threads
333          * participating in this io share the same session.
334          */
335         int  (*coo_io_init)(const struct lu_env *env,
336                             struct cl_object *obj, struct cl_io *io);
337         /**
338          * Fill portion of \a attr that this layer controls. This method is
339          * called top-to-bottom through all object layers.
340          *
341          * \pre cl_object_header::coh_attr_guard of the top-object is locked.
342          *
343          * \return   0: to continue
344          * \return +ve: to stop iterating through layers (but 0 is returned
345          *              from enclosing cl_object_attr_get())
346          * \return -ve: to signal error
347          */
348         int (*coo_attr_get)(const struct lu_env *env, struct cl_object *obj,
349                             struct cl_attr *attr);
350         /**
351          * Update attributes.
352          *
353          * \a valid is a bitmask composed from enum #cl_attr_valid, and
354          * indicating what attributes are to be set.
355          *
356          * \pre cl_object_header::coh_attr_guard of the top-object is locked.
357          *
358          * \return the same convention as for
359          * cl_object_operations::coo_attr_get() is used.
360          */
361         int (*coo_attr_update)(const struct lu_env *env, struct cl_object *obj,
362                                const struct cl_attr *attr, unsigned valid);
363         /**
364          * Update object configuration. Called top-to-bottom to modify object
365          * configuration.
366          *
367          * XXX error conditions and handling.
368          */
369         int (*coo_conf_set)(const struct lu_env *env, struct cl_object *obj,
370                             const struct cl_object_conf *conf);
371         /**
372          * Glimpse ast. Executed when glimpse ast arrives for a lock on this
373          * object. Layers are supposed to fill parts of \a lvb that will be
374          * shipped to the glimpse originator as a glimpse result.
375          *
376          * \see vvp_object_glimpse(), lovsub_object_glimpse(),
377          * \see osc_object_glimpse()
378          */
379         int (*coo_glimpse)(const struct lu_env *env,
380                            const struct cl_object *obj, struct ost_lvb *lvb);
381         /**
382          * Object prune method. Called when the layout is going to change on
383          * this object, therefore each layer has to clean up their cache,
384          * mainly pages and locks.
385          */
386         int (*coo_prune)(const struct lu_env *env, struct cl_object *obj);
387         /**
388          * Object getstripe method.
389          */
390         int (*coo_getstripe)(const struct lu_env *env, struct cl_object *obj,
391                              struct lov_user_md __user *lum);
392         /**
393          * Get FIEMAP mapping from the object.
394          */
395         int (*coo_fiemap)(const struct lu_env *env, struct cl_object *obj,
396                           struct ll_fiemap_info_key *fmkey,
397                           struct fiemap *fiemap, size_t *buflen);
398         /**
399          * Get layout and generation of the object.
400          */
401         int (*coo_layout_get)(const struct lu_env *env, struct cl_object *obj,
402                               struct cl_layout *layout);
403         /**
404          * Get maximum size of the object.
405          */
406         loff_t (*coo_maxbytes)(struct cl_object *obj);
407         /**
408          * Set request attributes.
409          */
410         void (*coo_req_attr_set)(const struct lu_env *env,
411                                  struct cl_object *obj,
412                                  struct cl_req_attr *attr);
413 };
414
415 /**
416  * Extended header for client object.
417  */
418 struct cl_object_header {
419         /** Standard lu_object_header. cl_object::co_lu::lo_header points
420          * here. */
421         struct lu_object_header coh_lu;
422
423         /**
424          * Parent object. It is assumed that an object has a well-defined
425          * parent, but not a well-defined child (there may be multiple
426          * sub-objects, for the same top-object). cl_object_header::coh_parent
427          * field allows certain code to be written generically, without
428          * limiting possible cl_object layouts unduly.
429          */
430         struct cl_object_header *coh_parent;
431         /**
432          * Protects consistency between cl_attr of parent object and
433          * attributes of sub-objects, that the former is calculated ("merged")
434          * from.
435          *
436          * \todo XXX this can be read/write lock if needed.
437          */
438         spinlock_t               coh_attr_guard;
439         /**
440          * Size of cl_page + page slices
441          */
442         unsigned short           coh_page_bufsize;
443         /**
444          * Number of objects above this one: 0 for a top-object, 1 for its
445          * sub-object, etc.
446          */
447         unsigned char            coh_nesting;
448 };
449
450 /**
451  * Helper macro: iterate over all layers of the object \a obj, assigning every
452  * layer top-to-bottom to \a slice.
453  */
454 #define cl_object_for_each(slice, obj)                          \
455         list_for_each_entry((slice),                            \
456                             &(obj)->co_lu.lo_header->loh_layers,\
457                             co_lu.lo_linkage)
458
459 /**
460  * Helper macro: iterate over all layers of the object \a obj, assigning every
461  * layer bottom-to-top to \a slice.
462  */
463 #define cl_object_for_each_reverse(slice, obj)                          \
464         list_for_each_entry_reverse((slice),                            \
465                                     &(obj)->co_lu.lo_header->loh_layers,\
466                                     co_lu.lo_linkage)
467
468 /** @} cl_object */
469
470 #define CL_PAGE_EOF ((pgoff_t)~0ull)
471
472 /** \addtogroup cl_page cl_page
473  * @{ */
474
475 /** \struct cl_page
476  * Layered client page.
477  *
478  * cl_page: represents a portion of a file, cached in the memory. All pages
479  *    of the given file are of the same size, and are kept in the radix tree
480  *    hanging off the cl_object. cl_page doesn't fan out, but as sub-objects
481  *    of the top-level file object are first class cl_objects, they have their
482  *    own radix trees of pages and hence page is implemented as a sequence of
483  *    struct cl_pages's, linked into double-linked list through
484  *    cl_page::cp_parent and cl_page::cp_child pointers, each residing in the
485  *    corresponding radix tree at the corresponding logical offset.
486  *
487  * cl_page is associated with VM page of the hosting environment (struct
488  *    page in Linux kernel, for example), struct page. It is assumed, that this
489  *    association is implemented by one of cl_page layers (top layer in the
490  *    current design) that
491  *
492  *        - intercepts per-VM-page call-backs made by the environment (e.g.,
493  *          memory pressure),
494  *
495  *        - translates state (page flag bits) and locking between lustre and
496  *          environment.
497  *
498  *    The association between cl_page and struct page is immutable and
499  *    established when cl_page is created.
500  *
501  * cl_page can be "owned" by a particular cl_io (see below), guaranteeing
502  *    this io an exclusive access to this page w.r.t. other io attempts and
503  *    various events changing page state (such as transfer completion, or
504  *    eviction of the page from the memory). Note, that in general cl_io
505  *    cannot be identified with a particular thread, and page ownership is not
506  *    exactly equal to the current thread holding a lock on the page. Layer
507  *    implementing association between cl_page and struct page has to implement
508  *    ownership on top of available synchronization mechanisms.
509  *
510  *    While lustre client maintains the notion of an page ownership by io,
511  *    hosting MM/VM usually has its own page concurrency control
512  *    mechanisms. For example, in Linux, page access is synchronized by the
513  *    per-page PG_locked bit-lock, and generic kernel code (generic_file_*())
514  *    takes care to acquire and release such locks as necessary around the
515  *    calls to the file system methods (->readpage(), ->prepare_write(),
516  *    ->commit_write(), etc.). This leads to the situation when there are two
517  *    different ways to own a page in the client:
518  *
519  *        - client code explicitly and voluntary owns the page (cl_page_own());
520  *
521  *        - VM locks a page and then calls the client, that has "to assume"
522  *          the ownership from the VM (cl_page_assume()).
523  *
524  *    Dual methods to release ownership are cl_page_disown() and
525  *    cl_page_unassume().
526  *
527  * cl_page is reference counted (cl_page::cp_ref). When reference counter
528  *    drops to 0, the page is returned to the cache, unless it is in
529  *    cl_page_state::CPS_FREEING state, in which case it is immediately
530  *    destroyed.
531  *
532  *    The general logic guaranteeing the absence of "existential races" for
533  *    pages is the following:
534  *
535  *        - there are fixed known ways for a thread to obtain a new reference
536  *          to a page:
537  *
538  *            - by doing a lookup in the cl_object radix tree, protected by the
539  *              spin-lock;
540  *
541  *            - by starting from VM-locked struct page and following some
542  *              hosting environment method (e.g., following ->private pointer in
543  *              the case of Linux kernel), see cl_vmpage_page();
544  *
545  *        - when the page enters cl_page_state::CPS_FREEING state, all these
546  *          ways are severed with the proper synchronization
547  *          (cl_page_delete());
548  *
549  *        - entry into cl_page_state::CPS_FREEING is serialized by the VM page
550  *          lock;
551  *
552  *        - no new references to the page in cl_page_state::CPS_FREEING state
553  *          are allowed (checked in cl_page_get()).
554  *
555  *    Together this guarantees that when last reference to a
556  *    cl_page_state::CPS_FREEING page is released, it is safe to destroy the
557  *    page, as neither references to it can be acquired at that point, nor
558  *    ones exist.
559  *
560  * cl_page is a state machine. States are enumerated in enum
561  *    cl_page_state. Possible state transitions are enumerated in
562  *    cl_page_state_set(). State transition process (i.e., actual changing of
563  *    cl_page::cp_state field) is protected by the lock on the underlying VM
564  *    page.
565  *
566  * Linux Kernel implementation.
567  *
568  *    Binding between cl_page and struct page (which is a typedef for
569  *    struct page) is implemented in the vvp layer. cl_page is attached to the
570  *    ->private pointer of the struct page, together with the setting of
571  *    PG_private bit in page->flags, and acquiring additional reference on the
572  *    struct page (much like struct buffer_head, or any similar file system
573  *    private data structures).
574  *
575  *    PG_locked lock is used to implement both ownership and transfer
576  *    synchronization, that is, page is VM-locked in CPS_{OWNED,PAGE{IN,OUT}}
577  *    states. No additional references are acquired for the duration of the
578  *    transfer.
579  *
580  * \warning *THIS IS NOT* the behavior expected by the Linux kernel, where
581  *          write-out is "protected" by the special PG_writeback bit.
582  */
583
584 /**
585  * States of cl_page. cl_page.c assumes particular order here.
586  *
587  * The page state machine is rather crude, as it doesn't recognize finer page
588  * states like "dirty" or "up to date". This is because such states are not
589  * always well defined for the whole stack (see, for example, the
590  * implementation of the read-ahead, that hides page up-to-dateness to track
591  * cache hits accurately). Such sub-states are maintained by the layers that
592  * are interested in them.
593  */
594 enum cl_page_state {
595         /**
596          * Page is in the cache, un-owned. Page leaves cached state in the
597          * following cases:
598          *
599          *     - [cl_page_state::CPS_OWNED] io comes across the page and
600          *     owns it;
601          *
602          *     - [cl_page_state::CPS_PAGEOUT] page is dirty, the
603          *     req-formation engine decides that it wants to include this page
604          *     into an RPC being constructed, and yanks it from the cache;
605          *
606          *     - [cl_page_state::CPS_FREEING] VM callback is executed to
607          *     evict the page form the memory;
608          *
609          * \invariant cl_page::cp_owner == NULL && cl_page::cp_req == NULL
610          */
611         CPS_CACHED,
612         /**
613          * Page is exclusively owned by some cl_io. Page may end up in this
614          * state as a result of
615          *
616          *     - io creating new page and immediately owning it;
617          *
618          *     - [cl_page_state::CPS_CACHED] io finding existing cached page
619          *     and owning it;
620          *
621          *     - [cl_page_state::CPS_OWNED] io finding existing owned page
622          *     and waiting for owner to release the page;
623          *
624          * Page leaves owned state in the following cases:
625          *
626          *     - [cl_page_state::CPS_CACHED] io decides to leave the page in
627          *     the cache, doing nothing;
628          *
629          *     - [cl_page_state::CPS_PAGEIN] io starts read transfer for
630          *     this page;
631          *
632          *     - [cl_page_state::CPS_PAGEOUT] io starts immediate write
633          *     transfer for this page;
634          *
635          *     - [cl_page_state::CPS_FREEING] io decides to destroy this
636          *     page (e.g., as part of truncate or extent lock cancellation).
637          *
638          * \invariant cl_page::cp_owner != NULL && cl_page::cp_req == NULL
639          */
640         CPS_OWNED,
641         /**
642          * Page is being written out, as a part of a transfer. This state is
643          * entered when req-formation logic decided that it wants this page to
644          * be sent through the wire _now_. Specifically, it means that once
645          * this state is achieved, transfer completion handler (with either
646          * success or failure indication) is guaranteed to be executed against
647          * this page independently of any locks and any scheduling decisions
648          * made by the hosting environment (that effectively means that the
649          * page is never put into cl_page_state::CPS_PAGEOUT state "in
650          * advance". This property is mentioned, because it is important when
651          * reasoning about possible dead-locks in the system). The page can
652          * enter this state as a result of
653          *
654          *     - [cl_page_state::CPS_OWNED] an io requesting an immediate
655          *     write-out of this page, or
656          *
657          *     - [cl_page_state::CPS_CACHED] req-forming engine deciding
658          *     that it has enough dirty pages cached to issue a "good"
659          *     transfer.
660          *
661          * The page leaves cl_page_state::CPS_PAGEOUT state when the transfer
662          * is completed---it is moved into cl_page_state::CPS_CACHED state.
663          *
664          * Underlying VM page is locked for the duration of transfer.
665          *
666          * \invariant: cl_page::cp_owner == NULL && cl_page::cp_req != NULL
667          */
668         CPS_PAGEOUT,
669         /**
670          * Page is being read in, as a part of a transfer. This is quite
671          * similar to the cl_page_state::CPS_PAGEOUT state, except that
672          * read-in is always "immediate"---there is no such thing a sudden
673          * construction of read request from cached, presumably not up to date,
674          * pages.
675          *
676          * Underlying VM page is locked for the duration of transfer.
677          *
678          * \invariant: cl_page::cp_owner == NULL && cl_page::cp_req != NULL
679          */
680         CPS_PAGEIN,
681         /**
682          * Page is being destroyed. This state is entered when client decides
683          * that page has to be deleted from its host object, as, e.g., a part
684          * of truncate.
685          *
686          * Once this state is reached, there is no way to escape it.
687          *
688          * \invariant: cl_page::cp_owner == NULL && cl_page::cp_req == NULL
689          */
690         CPS_FREEING,
691         CPS_NR
692 };
693
694 enum cl_page_type {
695         /** Host page, the page is from the host inode which the cl_page
696          * belongs to. */
697         CPT_CACHEABLE = 1,
698
699         /** Transient page, the transient cl_page is used to bind a cl_page
700          *  to vmpage which is not belonging to the same object of cl_page.
701          *  it is used in DirectIO, lockless IO and liblustre. */
702         CPT_TRANSIENT,
703 };
704
705 /**
706  * Fields are protected by the lock on struct page, except for atomics and
707  * immutables.
708  *
709  * \invariant Data type invariants are in cl_page_invariant(). Basically:
710  * cl_page::cp_parent and cl_page::cp_child are a well-formed double-linked
711  * list, consistent with the parent/child pointers in the cl_page::cp_obj and
712  * cl_page::cp_owner (when set).
713  */
714 struct cl_page {
715         /** Reference counter. */
716         atomic_t                 cp_ref;
717         /** Transfer error. */
718         int                      cp_error;
719         /** An object this page is a part of. Immutable after creation. */
720         struct cl_object        *cp_obj;
721         /** vmpage */
722         struct page             *cp_vmpage;
723         /** Linkage of pages within group. Pages must be owned */
724         struct list_head         cp_batch;
725         /** List of slices. Immutable after creation. */
726         struct list_head         cp_layers;
727         /**
728          * Page state. This field is const to avoid accidental update, it is
729          * modified only internally within cl_page.c. Protected by a VM lock.
730          */
731         const enum cl_page_state cp_state;
732         /**
733          * Page type. Only CPT_TRANSIENT is used so far. Immutable after
734          * creation.
735          */
736         enum cl_page_type        cp_type;
737
738         /**
739          * Owning IO in cl_page_state::CPS_OWNED state. Sub-page can be owned
740          * by sub-io. Protected by a VM lock.
741          */
742         struct cl_io            *cp_owner;
743         /** List of references to this page, for debugging. */
744         struct lu_ref            cp_reference;
745         /** Link to an object, for debugging. */
746         struct lu_ref_link       cp_obj_ref;
747         /** Link to a queue, for debugging. */
748         struct lu_ref_link       cp_queue_ref;
749         /** Assigned if doing a sync_io */
750         struct cl_sync_io       *cp_sync_io;
751 };
752
753 /**
754  * Per-layer part of cl_page.
755  *
756  * \see vvp_page, lov_page, osc_page
757  */
758 struct cl_page_slice {
759         struct cl_page                  *cpl_page;
760         pgoff_t                          cpl_index;
761         /**
762          * Object slice corresponding to this page slice. Immutable after
763          * creation.
764          */
765         struct cl_object                *cpl_obj;
766         const struct cl_page_operations *cpl_ops;
767         /** Linkage into cl_page::cp_layers. Immutable after creation. */
768         struct list_head                 cpl_linkage;
769 };
770
771 /**
772  * Lock mode. For the client extent locks.
773  *
774  * \ingroup cl_lock
775  */
776 enum cl_lock_mode {
777         CLM_READ,
778         CLM_WRITE,
779         CLM_GROUP,
780         CLM_MAX,
781 };
782
783 /**
784  * Requested transfer type.
785  */
786 enum cl_req_type {
787         CRT_READ,
788         CRT_WRITE,
789         CRT_NR
790 };
791
792 /**
793  * Per-layer page operations.
794  *
795  * Methods taking an \a io argument are for the activity happening in the
796  * context of given \a io. Page is assumed to be owned by that io, except for
797  * the obvious cases (like cl_page_operations::cpo_own()).
798  *
799  * \see vvp_page_ops, lov_page_ops, osc_page_ops
800  */
801 struct cl_page_operations {
802         /**
803          * cl_page<->struct page methods. Only one layer in the stack has to
804          * implement these. Current code assumes that this functionality is
805          * provided by the topmost layer, see cl_page_disown0() as an example.
806          */
807
808         /**
809          * Called when \a io acquires this page into the exclusive
810          * ownership. When this method returns, it is guaranteed that the is
811          * not owned by other io, and no transfer is going on against
812          * it. Optional.
813          *
814          * \see cl_page_own()
815          * \see vvp_page_own(), lov_page_own()
816          */
817         int  (*cpo_own)(const struct lu_env *env,
818                         const struct cl_page_slice *slice,
819                         struct cl_io *io, int nonblock);
820         /** Called when ownership it yielded. Optional.
821          *
822          * \see cl_page_disown()
823          * \see vvp_page_disown()
824          */
825         void (*cpo_disown)(const struct lu_env *env,
826                            const struct cl_page_slice *slice, struct cl_io *io);
827         /**
828          * Called for a page that is already "owned" by \a io from VM point of
829          * view. Optional.
830          *
831          * \see cl_page_assume()
832          * \see vvp_page_assume(), lov_page_assume()
833          */
834         void (*cpo_assume)(const struct lu_env *env,
835                            const struct cl_page_slice *slice, struct cl_io *io);
836         /** Dual to cl_page_operations::cpo_assume(). Optional. Called
837          * bottom-to-top when IO releases a page without actually unlocking
838          * it.
839          *
840          * \see cl_page_unassume()
841          * \see vvp_page_unassume()
842          */
843         void (*cpo_unassume)(const struct lu_env *env,
844                              const struct cl_page_slice *slice,
845                              struct cl_io *io);
846         /**
847          * Announces whether the page contains valid data or not by \a uptodate.
848          *
849          * \see cl_page_export()
850          * \see vvp_page_export()
851          */
852         void  (*cpo_export)(const struct lu_env *env,
853                             const struct cl_page_slice *slice, int uptodate);
854         /**
855          * Checks whether underlying VM page is locked (in the suitable
856          * sense). Used for assertions.
857          *
858          * \retval    -EBUSY: page is protected by a lock of a given mode;
859          * \retval  -ENODATA: page is not protected by a lock;
860          * \retval         0: this layer cannot decide. (Should never happen.)
861          */
862         int (*cpo_is_vmlocked)(const struct lu_env *env,
863                                const struct cl_page_slice *slice);
864         /**
865          * Page destruction.
866          */
867
868         /**
869          * Called when page is truncated from the object. Optional.
870          *
871          * \see cl_page_discard()
872          * \see vvp_page_discard(), osc_page_discard()
873          */
874         void (*cpo_discard)(const struct lu_env *env,
875                             const struct cl_page_slice *slice,
876                             struct cl_io *io);
877         /**
878          * Called when page is removed from the cache, and is about to being
879          * destroyed. Optional.
880          *
881          * \see cl_page_delete()
882          * \see vvp_page_delete(), osc_page_delete()
883          */
884         void (*cpo_delete)(const struct lu_env *env,
885                            const struct cl_page_slice *slice);
886         /** Destructor. Frees resources and slice itself. */
887         void (*cpo_fini)(const struct lu_env *env,
888                          struct cl_page_slice *slice);
889         /**
890          * Optional debugging helper. Prints given page slice.
891          *
892          * \see cl_page_print()
893          */
894         int (*cpo_print)(const struct lu_env *env,
895                          const struct cl_page_slice *slice,
896                          void *cookie, lu_printer_t p);
897         /**
898          * \name transfer
899          *
900          * Transfer methods.
901          *
902          * @{
903          */
904         /**
905          * Request type dependent vector of operations.
906          *
907          * Transfer operations depend on transfer mode (cl_req_type). To avoid
908          * passing transfer mode to each and every of these methods, and to
909          * avoid branching on request type inside of the methods, separate
910          * methods for cl_req_type:CRT_READ and cl_req_type:CRT_WRITE are
911          * provided. That is, method invocation usually looks like
912          *
913          *         slice->cp_ops.io[req->crq_type].cpo_method(env, slice, ...);
914          */
915         struct {
916                 /**
917                  * Called when a page is submitted for a transfer as a part of
918                  * cl_page_list.
919                  *
920                  * \return    0         : page is eligible for submission;
921                  * \return    -EALREADY : skip this page;
922                  * \return    -ve       : error.
923                  *
924                  * \see cl_page_prep()
925                  */
926                 int  (*cpo_prep)(const struct lu_env *env,
927                                  const struct cl_page_slice *slice,
928                                  struct cl_io *io);
929                 /**
930                  * Completion handler. This is guaranteed to be eventually
931                  * fired after cl_page_operations::cpo_prep() or
932                  * cl_page_operations::cpo_make_ready() call.
933                  *
934                  * This method can be called in a non-blocking context. It is
935                  * guaranteed however, that the page involved and its object
936                  * are pinned in memory (and, hence, calling cl_page_put() is
937                  * safe).
938                  *
939                  * \see cl_page_completion()
940                  */
941                 void (*cpo_completion)(const struct lu_env *env,
942                                        const struct cl_page_slice *slice,
943                                        int ioret);
944                 /**
945                  * Called when cached page is about to be added to the
946                  * ptlrpc request as a part of req formation.
947                  *
948                  * \return    0       : proceed with this page;
949                  * \return    -EAGAIN : skip this page;
950                  * \return    -ve     : error.
951                  *
952                  * \see cl_page_make_ready()
953                  */
954                 int  (*cpo_make_ready)(const struct lu_env *env,
955                                        const struct cl_page_slice *slice);
956         } io[CRT_NR];
957         /**
958          * Tell transfer engine that only [to, from] part of a page should be
959          * transmitted.
960          *
961          * This is used for immediate transfers.
962          *
963          * \todo XXX this is not very good interface. It would be much better
964          * if all transfer parameters were supplied as arguments to
965          * cl_io_operations::cio_submit() call, but it is not clear how to do
966          * this for page queues.
967          *
968          * \see cl_page_clip()
969          */
970         void (*cpo_clip)(const struct lu_env *env,
971                          const struct cl_page_slice *slice,
972                          int from, int to);
973         /**
974          * \pre  the page was queued for transferring.
975          * \post page is removed from client's pending list, or -EBUSY
976          *       is returned if it has already been in transferring.
977          *
978          * This is one of seldom page operation which is:
979          * 0. called from top level;
980          * 1. don't have vmpage locked;
981          * 2. every layer should synchronize execution of its ->cpo_cancel()
982          *    with completion handlers. Osc uses client obd lock for this
983          *    purpose. Based on there is no vvp_page_cancel and
984          *    lov_page_cancel(), cpo_cancel is defacto protected by client lock.
985          *
986          * \see osc_page_cancel().
987          */
988         int (*cpo_cancel)(const struct lu_env *env,
989                           const struct cl_page_slice *slice);
990         /**
991          * Write out a page by kernel. This is only called by ll_writepage
992          * right now.
993          *
994          * \see cl_page_flush()
995          */
996         int (*cpo_flush)(const struct lu_env *env,
997                          const struct cl_page_slice *slice,
998                          struct cl_io *io);
999         /** @} transfer */
1000 };
1001
1002 /**
1003  * Helper macro, dumping detailed information about \a page into a log.
1004  */
1005 #define CL_PAGE_DEBUG(mask, env, page, format, ...)                     \
1006 do {                                                                    \
1007         if (cfs_cdebug_show(mask, DEBUG_SUBSYSTEM)) {                   \
1008                 LIBCFS_DEBUG_MSG_DATA_DECL(msgdata, mask, NULL);        \
1009                 cl_page_print(env, &msgdata, lu_cdebug_printer, page);  \
1010                 CDEBUG(mask, format , ## __VA_ARGS__);                  \
1011         }                                                               \
1012 } while (0)
1013
1014 /**
1015  * Helper macro, dumping shorter information about \a page into a log.
1016  */
1017 #define CL_PAGE_HEADER(mask, env, page, format, ...)                          \
1018 do {                                                                          \
1019         if (cfs_cdebug_show(mask, DEBUG_SUBSYSTEM)) {                         \
1020                 LIBCFS_DEBUG_MSG_DATA_DECL(msgdata, mask, NULL);              \
1021                 cl_page_header_print(env, &msgdata, lu_cdebug_printer, page); \
1022                 CDEBUG(mask, format , ## __VA_ARGS__);                        \
1023         }                                                                     \
1024 } while (0)
1025
1026 static inline struct page *cl_page_vmpage(const struct cl_page *page)
1027 {
1028         LASSERT(page->cp_vmpage != NULL);
1029         return page->cp_vmpage;
1030 }
1031
1032 /**
1033  * Check if a cl_page is in use.
1034  *
1035  * Client cache holds a refcount, this refcount will be dropped when
1036  * the page is taken out of cache, see vvp_page_delete().
1037  */
1038 static inline bool __page_in_use(const struct cl_page *page, int refc)
1039 {
1040         return (atomic_read(&page->cp_ref) > refc + 1);
1041 }
1042
1043 /**
1044  * Caller itself holds a refcount of cl_page.
1045  */
1046 #define cl_page_in_use(pg)       __page_in_use(pg, 1)
1047 /**
1048  * Caller doesn't hold a refcount.
1049  */
1050 #define cl_page_in_use_noref(pg) __page_in_use(pg, 0)
1051
1052 /** @} cl_page */
1053
1054 /** \addtogroup cl_lock cl_lock
1055  * @{ */
1056 /** \struct cl_lock
1057  *
1058  * Extent locking on the client.
1059  *
1060  * LAYERING
1061  *
1062  * The locking model of the new client code is built around
1063  *
1064  *        struct cl_lock
1065  *
1066  * data-type representing an extent lock on a regular file. cl_lock is a
1067  * layered object (much like cl_object and cl_page), it consists of a header
1068  * (struct cl_lock) and a list of layers (struct cl_lock_slice), linked to
1069  * cl_lock::cll_layers list through cl_lock_slice::cls_linkage.
1070  *
1071  * Typical cl_lock consists of the two layers:
1072  *
1073  *     - vvp_lock (vvp specific data), and
1074  *     - lov_lock (lov specific data).
1075  *
1076  * lov_lock contains an array of sub-locks. Each of these sub-locks is a
1077  * normal cl_lock: it has a header (struct cl_lock) and a list of layers:
1078  *
1079  *     - lovsub_lock, and
1080  *     - osc_lock
1081  *
1082  * Each sub-lock is associated with a cl_object (representing stripe
1083  * sub-object or the file to which top-level cl_lock is associated to), and is
1084  * linked into that cl_object::coh_locks. In this respect cl_lock is similar to
1085  * cl_object (that at lov layer also fans out into multiple sub-objects), and
1086  * is different from cl_page, that doesn't fan out (there is usually exactly
1087  * one osc_page for every vvp_page). We shall call vvp-lov portion of the lock
1088  * a "top-lock" and its lovsub-osc portion a "sub-lock".
1089  *
1090  * LIFE CYCLE
1091  *
1092  * cl_lock is a cacheless data container for the requirements of locks to
1093  * complete the IO. cl_lock is created before I/O starts and destroyed when the
1094  * I/O is complete.
1095  *
1096  * cl_lock depends on LDLM lock to fulfill lock semantics. LDLM lock is attached
1097  * to cl_lock at OSC layer. LDLM lock is still cacheable.
1098  *
1099  * INTERFACE AND USAGE
1100  *
1101  * Two major methods are supported for cl_lock: clo_enqueue and clo_cancel.  A
1102  * cl_lock is enqueued by cl_lock_request(), which will call clo_enqueue()
1103  * methods for each layer to enqueue the lock. At the LOV layer, if a cl_lock
1104  * consists of multiple sub cl_locks, each sub locks will be enqueued
1105  * correspondingly. At OSC layer, the lock enqueue request will tend to reuse
1106  * cached LDLM lock; otherwise a new LDLM lock will have to be requested from
1107  * OST side.
1108  *
1109  * cl_lock_cancel() must be called to release a cl_lock after use. clo_cancel()
1110  * method will be called for each layer to release the resource held by this
1111  * lock. At OSC layer, the reference count of LDLM lock, which is held at
1112  * clo_enqueue time, is released.
1113  *
1114  * LDLM lock can only be canceled if there is no cl_lock using it.
1115  *
1116  * Overall process of the locking during IO operation is as following:
1117  *
1118  *     - once parameters for IO are setup in cl_io, cl_io_operations::cio_lock()
1119  *       is called on each layer. Responsibility of this method is to add locks,
1120  *       needed by a given layer into cl_io.ci_lockset.
1121  *
1122  *     - once locks for all layers were collected, they are sorted to avoid
1123  *       dead-locks (cl_io_locks_sort()), and enqueued.
1124  *
1125  *     - when all locks are acquired, IO is performed;
1126  *
1127  *     - locks are released after IO is complete.
1128  *
1129  * Striping introduces major additional complexity into locking. The
1130  * fundamental problem is that it is generally unsafe to actively use (hold)
1131  * two locks on the different OST servers at the same time, as this introduces
1132  * inter-server dependency and can lead to cascading evictions.
1133  *
1134  * Basic solution is to sub-divide large read/write IOs into smaller pieces so
1135  * that no multi-stripe locks are taken (note that this design abandons POSIX
1136  * read/write semantics). Such pieces ideally can be executed concurrently. At
1137  * the same time, certain types of IO cannot be sub-divived, without
1138  * sacrificing correctness. This includes:
1139  *
1140  *  - O_APPEND write, where [0, EOF] lock has to be taken, to guarantee
1141  *  atomicity;
1142  *
1143  *  - ftruncate(fd, offset), where [offset, EOF] lock has to be taken.
1144  *
1145  * Also, in the case of read(fd, buf, count) or write(fd, buf, count), where
1146  * buf is a part of memory mapped Lustre file, a lock or locks protecting buf
1147  * has to be held together with the usual lock on [offset, offset + count].
1148  *
1149  * Interaction with DLM
1150  *
1151  * In the expected setup, cl_lock is ultimately backed up by a collection of
1152  * DLM locks (struct ldlm_lock). Association between cl_lock and DLM lock is
1153  * implemented in osc layer, that also matches DLM events (ASTs, cancellation,
1154  * etc.) into cl_lock_operation calls. See struct osc_lock for a more detailed
1155  * description of interaction with DLM.
1156  */
1157
1158 /**
1159  * Lock description.
1160  */
1161 struct cl_lock_descr {
1162         /** Object this lock is granted for. */
1163         struct cl_object *cld_obj;
1164         /** Index of the first page protected by this lock. */
1165         pgoff_t           cld_start;
1166         /** Index of the last page (inclusive) protected by this lock. */
1167         pgoff_t           cld_end;
1168         /** Group ID, for group lock */
1169         __u64             cld_gid;
1170         /** Lock mode. */
1171         enum cl_lock_mode cld_mode;
1172         /**
1173          * flags to enqueue lock. A combination of bit-flags from
1174          * enum cl_enq_flags.
1175          */
1176         __u32             cld_enq_flags;
1177 };
1178
1179 #define DDESCR "%s(%d):[%lu, %lu]:%x"
1180 #define PDESCR(descr)                                                   \
1181         cl_lock_mode_name((descr)->cld_mode), (descr)->cld_mode,        \
1182         (descr)->cld_start, (descr)->cld_end, (descr)->cld_enq_flags
1183
1184 const char *cl_lock_mode_name(const enum cl_lock_mode mode);
1185
1186 /**
1187  * Layered client lock.
1188  */
1189 struct cl_lock {
1190         /** List of slices. Immutable after creation. */
1191         struct list_head      cll_layers;
1192         /** lock attribute, extent, cl_object, etc. */
1193         struct cl_lock_descr  cll_descr;
1194 };
1195
1196 /**
1197  * Per-layer part of cl_lock
1198  *
1199  * \see vvp_lock, lov_lock, lovsub_lock, osc_lock
1200  */
1201 struct cl_lock_slice {
1202         struct cl_lock                  *cls_lock;
1203         /** Object slice corresponding to this lock slice. Immutable after
1204          * creation. */
1205         struct cl_object                *cls_obj;
1206         const struct cl_lock_operations *cls_ops;
1207         /** Linkage into cl_lock::cll_layers. Immutable after creation. */
1208         struct list_head                 cls_linkage;
1209 };
1210
1211 /**
1212  *
1213  * \see vvp_lock_ops, lov_lock_ops, lovsub_lock_ops, osc_lock_ops
1214  */
1215 struct cl_lock_operations {
1216         /** @{ */
1217         /**
1218          * Attempts to enqueue the lock. Called top-to-bottom.
1219          *
1220          * \retval 0    this layer has enqueued the lock successfully
1221          * \retval >0   this layer has enqueued the lock, but need to wait on
1222          *              @anchor for resources
1223          * \retval -ve  failure
1224          *
1225          * \see vvp_lock_enqueue(), lov_lock_enqueue(), lovsub_lock_enqueue(),
1226          * \see osc_lock_enqueue()
1227          */
1228         int  (*clo_enqueue)(const struct lu_env *env,
1229                             const struct cl_lock_slice *slice,
1230                             struct cl_io *io, struct cl_sync_io *anchor);
1231         /**
1232          * Cancel a lock, release its DLM lock ref, while does not cancel the
1233          * DLM lock
1234          */
1235         void (*clo_cancel)(const struct lu_env *env,
1236                            const struct cl_lock_slice *slice);
1237         /** @} */
1238         /**
1239          * Destructor. Frees resources and the slice.
1240          *
1241          * \see vvp_lock_fini(), lov_lock_fini(), lovsub_lock_fini(),
1242          * \see osc_lock_fini()
1243          */
1244         void (*clo_fini)(const struct lu_env *env, struct cl_lock_slice *slice);
1245         /**
1246          * Optional debugging helper. Prints given lock slice.
1247          */
1248         int (*clo_print)(const struct lu_env *env,
1249                          void *cookie, lu_printer_t p,
1250                          const struct cl_lock_slice *slice);
1251 };
1252
1253 #define CL_LOCK_DEBUG(mask, env, lock, format, ...)                     \
1254 do {                                                                    \
1255         if (cfs_cdebug_show(mask, DEBUG_SUBSYSTEM)) {                   \
1256                 LIBCFS_DEBUG_MSG_DATA_DECL(msgdata, mask, NULL);        \
1257                 cl_lock_print(env, &msgdata, lu_cdebug_printer, lock);  \
1258                 CDEBUG(mask, format , ## __VA_ARGS__);                  \
1259         }                                                               \
1260 } while (0)
1261
1262 #define CL_LOCK_ASSERT(expr, env, lock) do {                            \
1263         if (likely(expr))                                               \
1264                 break;                                                  \
1265                                                                         \
1266         CL_LOCK_DEBUG(D_ERROR, env, lock, "failed at %s.\n", #expr);    \
1267         LBUG();                                                         \
1268 } while (0)
1269
1270 /** @} cl_lock */
1271
1272 /** \addtogroup cl_page_list cl_page_list
1273  * Page list used to perform collective operations on a group of pages.
1274  *
1275  * Pages are added to the list one by one. cl_page_list acquires a reference
1276  * for every page in it. Page list is used to perform collective operations on
1277  * pages:
1278  *
1279  *     - submit pages for an immediate transfer,
1280  *
1281  *     - own pages on behalf of certain io (waiting for each page in turn),
1282  *
1283  *     - discard pages.
1284  *
1285  * When list is finalized, it releases references on all pages it still has.
1286  *
1287  * \todo XXX concurrency control.
1288  *
1289  * @{
1290  */
1291 struct cl_page_list {
1292         unsigned                 pl_nr;
1293         struct list_head         pl_pages;
1294         struct task_struct      *pl_owner;
1295 };
1296
1297 /** 
1298  * A 2-queue of pages. A convenience data-type for common use case, 2-queue
1299  * contains an incoming page list and an outgoing page list.
1300  */
1301 struct cl_2queue {
1302         struct cl_page_list c2_qin;
1303         struct cl_page_list c2_qout;
1304 };
1305
1306 /** @} cl_page_list */
1307
1308 /** \addtogroup cl_io cl_io
1309  * @{ */
1310 /** \struct cl_io
1311  * I/O
1312  *
1313  * cl_io represents a high level I/O activity like
1314  * read(2)/write(2)/truncate(2) system call, or cancellation of an extent
1315  * lock.
1316  *
1317  * cl_io is a layered object, much like cl_{object,page,lock} but with one
1318  * important distinction. We want to minimize number of calls to the allocator
1319  * in the fast path, e.g., in the case of read(2) when everything is cached:
1320  * client already owns the lock over region being read, and data are cached
1321  * due to read-ahead. To avoid allocation of cl_io layers in such situations,
1322  * per-layer io state is stored in the session, associated with the io, see
1323  * struct {vvp,lov,osc}_io for example. Sessions allocation is amortized
1324  * by using free-lists, see cl_env_get().
1325  *
1326  * There is a small predefined number of possible io types, enumerated in enum
1327  * cl_io_type.
1328  *
1329  * cl_io is a state machine, that can be advanced concurrently by the multiple
1330  * threads. It is up to these threads to control the concurrency and,
1331  * specifically, to detect when io is done, and its state can be safely
1332  * released.
1333  *
1334  * For read/write io overall execution plan is as following:
1335  *
1336  *     (0) initialize io state through all layers;
1337  *
1338  *     (1) loop: prepare chunk of work to do
1339  *
1340  *     (2) call all layers to collect locks they need to process current chunk
1341  *
1342  *     (3) sort all locks to avoid dead-locks, and acquire them
1343  *
1344  *     (4) process the chunk: call per-page methods
1345  *         cl_io_operations::cio_prepare_write(),
1346  *         cl_io_operations::cio_commit_write() for write)
1347  *
1348  *     (5) release locks
1349  *
1350  *     (6) repeat loop.
1351  *
1352  * To implement the "parallel IO mode", lov layer creates sub-io's (lazily to
1353  * address allocation efficiency issues mentioned above), and returns with the
1354  * special error condition from per-page method when current sub-io has to
1355  * block. This causes io loop to be repeated, and lov switches to the next
1356  * sub-io in its cl_io_operations::cio_iter_init() implementation.
1357  */
1358
1359 /** IO types */
1360 enum cl_io_type {
1361         /** read system call */
1362         CIT_READ,
1363         /** write system call */
1364         CIT_WRITE,
1365         /** truncate, utime system calls */
1366         CIT_SETATTR,
1367         /** get data version */
1368         CIT_DATA_VERSION,
1369         /**
1370          * page fault handling
1371          */
1372         CIT_FAULT,
1373         /**
1374          * fsync system call handling
1375          * To write out a range of file
1376          */
1377         CIT_FSYNC,
1378         /**
1379          * Miscellaneous io. This is used for occasional io activity that
1380          * doesn't fit into other types. Currently this is used for:
1381          *
1382          *     - cancellation of an extent lock. This io exists as a context
1383          *     to write dirty pages from under the lock being canceled back
1384          *     to the server;
1385          *
1386          *     - VM induced page write-out. An io context for writing page out
1387          *     for memory cleansing;
1388          *
1389          *     - glimpse. An io context to acquire glimpse lock.
1390          *
1391          *     - grouplock. An io context to acquire group lock.
1392          *
1393          * CIT_MISC io is used simply as a context in which locks and pages
1394          * are manipulated. Such io has no internal "process", that is,
1395          * cl_io_loop() is never called for it.
1396          */
1397         CIT_MISC,
1398         /**
1399          * ladvise handling
1400          * To give advice about access of a file
1401          */
1402         CIT_LADVISE,
1403         CIT_OP_NR
1404 };
1405
1406 /**
1407  * States of cl_io state machine
1408  */
1409 enum cl_io_state {
1410         /** Not initialized. */
1411         CIS_ZERO,
1412         /** Initialized. */
1413         CIS_INIT,
1414         /** IO iteration started. */
1415         CIS_IT_STARTED,
1416         /** Locks taken. */
1417         CIS_LOCKED,
1418         /** Actual IO is in progress. */
1419         CIS_IO_GOING,
1420         /** IO for the current iteration finished. */
1421         CIS_IO_FINISHED,
1422         /** Locks released. */
1423         CIS_UNLOCKED,
1424         /** Iteration completed. */
1425         CIS_IT_ENDED,
1426         /** cl_io finalized. */
1427         CIS_FINI
1428 };
1429
1430 /**
1431  * IO state private for a layer.
1432  *
1433  * This is usually embedded into layer session data, rather than allocated
1434  * dynamically.
1435  *
1436  * \see vvp_io, lov_io, osc_io
1437  */
1438 struct cl_io_slice {
1439         struct cl_io                    *cis_io;
1440         /** corresponding object slice. Immutable after creation. */
1441         struct cl_object                *cis_obj;
1442         /** io operations. Immutable after creation. */
1443         const struct cl_io_operations   *cis_iop;
1444         /**
1445          * linkage into a list of all slices for a given cl_io, hanging off
1446          * cl_io::ci_layers. Immutable after creation.
1447          */
1448         struct list_head                cis_linkage;
1449 };
1450
1451 typedef void (*cl_commit_cbt)(const struct lu_env *, struct cl_io *,
1452                               struct cl_page *);
1453
1454 struct cl_read_ahead {
1455         /* Maximum page index the readahead window will end.
1456          * This is determined DLM lock coverage, RPC and stripe boundary.
1457          * cra_end is included. */
1458         pgoff_t cra_end;
1459         /* optimal RPC size for this read, by pages */
1460         unsigned long cra_rpc_size;
1461         /* Release callback. If readahead holds resources underneath, this
1462          * function should be called to release it. */
1463         void    (*cra_release)(const struct lu_env *env, void *cbdata);
1464         /* Callback data for cra_release routine */
1465         void    *cra_cbdata;
1466 };
1467
1468 static inline void cl_read_ahead_release(const struct lu_env *env,
1469                                          struct cl_read_ahead *ra)
1470 {
1471         if (ra->cra_release != NULL)
1472                 ra->cra_release(env, ra->cra_cbdata);
1473         memset(ra, 0, sizeof(*ra));
1474 }
1475
1476
1477 /**
1478  * Per-layer io operations.
1479  * \see vvp_io_ops, lov_io_ops, lovsub_io_ops, osc_io_ops
1480  */
1481 struct cl_io_operations {
1482         /**
1483          * Vector of io state transition methods for every io type.
1484          *
1485          * \see cl_page_operations::io
1486          */
1487         struct {
1488                 /**
1489                  * Prepare io iteration at a given layer.
1490                  *
1491                  * Called top-to-bottom at the beginning of each iteration of
1492                  * "io loop" (if it makes sense for this type of io). Here
1493                  * layer selects what work it will do during this iteration.
1494                  *
1495                  * \see cl_io_operations::cio_iter_fini()
1496                  */
1497                 int (*cio_iter_init) (const struct lu_env *env,
1498                                       const struct cl_io_slice *slice);
1499                 /**
1500                  * Finalize io iteration.
1501                  *
1502                  * Called bottom-to-top at the end of each iteration of "io
1503                  * loop". Here layers can decide whether IO has to be
1504                  * continued.
1505                  *
1506                  * \see cl_io_operations::cio_iter_init()
1507                  */
1508                 void (*cio_iter_fini) (const struct lu_env *env,
1509                                        const struct cl_io_slice *slice);
1510                 /**
1511                  * Collect locks for the current iteration of io.
1512                  *
1513                  * Called top-to-bottom to collect all locks necessary for
1514                  * this iteration. This methods shouldn't actually enqueue
1515                  * anything, instead it should post a lock through
1516                  * cl_io_lock_add(). Once all locks are collected, they are
1517                  * sorted and enqueued in the proper order.
1518                  */
1519                 int  (*cio_lock) (const struct lu_env *env,
1520                                   const struct cl_io_slice *slice);
1521                 /**
1522                  * Finalize unlocking.
1523                  *
1524                  * Called bottom-to-top to finish layer specific unlocking
1525                  * functionality, after generic code released all locks
1526                  * acquired by cl_io_operations::cio_lock().
1527                  */
1528                 void  (*cio_unlock)(const struct lu_env *env,
1529                                     const struct cl_io_slice *slice);
1530                 /**
1531                  * Start io iteration.
1532                  *
1533                  * Once all locks are acquired, called top-to-bottom to
1534                  * commence actual IO. In the current implementation,
1535                  * top-level vvp_io_{read,write}_start() does all the work
1536                  * synchronously by calling generic_file_*(), so other layers
1537                  * are called when everything is done.
1538                  */
1539                 int  (*cio_start)(const struct lu_env *env,
1540                                   const struct cl_io_slice *slice);
1541                 /**
1542                  * Called top-to-bottom at the end of io loop. Here layer
1543                  * might wait for an unfinished asynchronous io.
1544                  */
1545                 void (*cio_end)  (const struct lu_env *env,
1546                                   const struct cl_io_slice *slice);
1547                 /**
1548                  * Called bottom-to-top to notify layers that read/write IO
1549                  * iteration finished, with \a nob bytes transferred.
1550                  */
1551                 void (*cio_advance)(const struct lu_env *env,
1552                                     const struct cl_io_slice *slice,
1553                                     size_t nob);
1554                 /**
1555                  * Called once per io, bottom-to-top to release io resources.
1556                  */
1557                 void (*cio_fini) (const struct lu_env *env,
1558                                   const struct cl_io_slice *slice);
1559         } op[CIT_OP_NR];
1560
1561         /**
1562          * Submit pages from \a queue->c2_qin for IO, and move
1563          * successfully submitted pages into \a queue->c2_qout. Return
1564          * non-zero if failed to submit even the single page. If
1565          * submission failed after some pages were moved into \a
1566          * queue->c2_qout, completion callback with non-zero ioret is
1567          * executed on them.
1568          */
1569         int  (*cio_submit)(const struct lu_env *env,
1570                         const struct cl_io_slice *slice,
1571                         enum cl_req_type crt,
1572                         struct cl_2queue *queue);
1573         /**
1574          * Queue async page for write.
1575          * The difference between cio_submit and cio_queue is that
1576          * cio_submit is for urgent request.
1577          */
1578         int  (*cio_commit_async)(const struct lu_env *env,
1579                         const struct cl_io_slice *slice,
1580                         struct cl_page_list *queue, int from, int to,
1581                         cl_commit_cbt cb);
1582         /**
1583          * Decide maximum read ahead extent
1584          *
1585          * \pre io->ci_type == CIT_READ
1586          */
1587         int (*cio_read_ahead)(const struct lu_env *env,
1588                               const struct cl_io_slice *slice,
1589                               pgoff_t start, struct cl_read_ahead *ra);
1590         /**
1591          * Optional debugging helper. Print given io slice.
1592          */
1593         int (*cio_print)(const struct lu_env *env, void *cookie,
1594                          lu_printer_t p, const struct cl_io_slice *slice);
1595 };
1596
1597 /**
1598  * Flags to lock enqueue procedure.
1599  * \ingroup cl_lock
1600  */
1601 enum cl_enq_flags {
1602         /**
1603          * instruct server to not block, if conflicting lock is found. Instead
1604          * -EWOULDBLOCK is returned immediately.
1605          */
1606         CEF_NONBLOCK     = 0x00000001,
1607         /**
1608          * take lock asynchronously (out of order), as it cannot
1609          * deadlock. This is for LDLM_FL_HAS_INTENT locks used for glimpsing.
1610          */
1611         CEF_ASYNC        = 0x00000002,
1612         /**
1613          * tell the server to instruct (though a flag in the blocking ast) an
1614          * owner of the conflicting lock, that it can drop dirty pages
1615          * protected by this lock, without sending them to the server.
1616          */
1617         CEF_DISCARD_DATA = 0x00000004,
1618         /**
1619          * tell the sub layers that it must be a `real' lock. This is used for
1620          * mmapped-buffer locks and glimpse locks that must be never converted
1621          * into lockless mode.
1622          *
1623          * \see vvp_mmap_locks(), cl_glimpse_lock().
1624          */
1625         CEF_MUST         = 0x00000008,
1626         /**
1627          * tell the sub layers that never request a `real' lock. This flag is
1628          * not used currently.
1629          *
1630          * cl_io::ci_lockreq and CEF_{MUST,NEVER} flags specify lockless
1631          * conversion policy: ci_lockreq describes generic information of lock
1632          * requirement for this IO, especially for locks which belong to the
1633          * object doing IO; however, lock itself may have precise requirements
1634          * that are described by the enqueue flags.
1635          */
1636         CEF_NEVER        = 0x00000010,
1637         /**
1638          * for async glimpse lock.
1639          */
1640         CEF_AGL          = 0x00000020,
1641         /**
1642          * enqueue a lock to test DLM lock existence.
1643          */
1644         CEF_PEEK        = 0x00000040,
1645         /**
1646          * Lock match only. Used by group lock in I/O as group lock
1647          * is known to exist.
1648          */
1649         CEF_LOCK_MATCH  = 0x00000080,
1650         /**
1651          * mask of enq_flags.
1652          */
1653         CEF_MASK         = 0x000000ff,
1654 };
1655
1656 /**
1657  * Link between lock and io. Intermediate structure is needed, because the
1658  * same lock can be part of multiple io's simultaneously.
1659  */
1660 struct cl_io_lock_link {
1661         /** linkage into one of cl_lockset lists. */
1662         struct list_head        cill_linkage;
1663         struct cl_lock          cill_lock;
1664         /** optional destructor */
1665         void                    (*cill_fini)(const struct lu_env *env,
1666                                              struct cl_io_lock_link *link);
1667 };
1668 #define cill_descr      cill_lock.cll_descr
1669
1670 /**
1671  * Lock-set represents a collection of locks, that io needs at a
1672  * time. Generally speaking, client tries to avoid holding multiple locks when
1673  * possible, because
1674  *
1675  *      - holding extent locks over multiple ost's introduces the danger of
1676  *        "cascading timeouts";
1677  *
1678  *      - holding multiple locks over the same ost is still dead-lock prone,
1679  *        see comment in osc_lock_enqueue(),
1680  *
1681  * but there are certain situations where this is unavoidable:
1682  *
1683  *      - O_APPEND writes have to take [0, EOF] lock for correctness;
1684  *
1685  *      - truncate has to take [new-size, EOF] lock for correctness;
1686  *
1687  *      - SNS has to take locks across full stripe for correctness;
1688  *
1689  *      - in the case when user level buffer, supplied to {read,write}(file0),
1690  *        is a part of a memory mapped lustre file, client has to take a dlm
1691  *        locks on file0, and all files that back up the buffer (or a part of
1692  *        the buffer, that is being processed in the current chunk, in any
1693  *        case, there are situations where at least 2 locks are necessary).
1694  *
1695  * In such cases we at least try to take locks in the same consistent
1696  * order. To this end, all locks are first collected, then sorted, and then
1697  * enqueued.
1698  */
1699 struct cl_lockset {
1700         /** locks to be acquired. */
1701         struct list_head  cls_todo;
1702         /** locks acquired. */
1703         struct list_head  cls_done;
1704 };
1705
1706 /**
1707  * Lock requirements(demand) for IO. It should be cl_io_lock_req,
1708  * but 'req' is always to be thought as 'request' :-)
1709  */
1710 enum cl_io_lock_dmd {
1711         /** Always lock data (e.g., O_APPEND). */
1712         CILR_MANDATORY = 0,
1713         /** Layers are free to decide between local and global locking. */
1714         CILR_MAYBE,
1715         /** Never lock: there is no cache (e.g., liblustre). */
1716         CILR_NEVER
1717 };
1718
1719 enum cl_fsync_mode {
1720         /** start writeback, do not wait for them to finish */
1721         CL_FSYNC_NONE  = 0,
1722         /** start writeback and wait for them to finish */
1723         CL_FSYNC_LOCAL = 1,
1724         /** discard all of dirty pages in a specific file range */
1725         CL_FSYNC_DISCARD = 2,
1726         /** start writeback and make sure they have reached storage before
1727          * return. OST_SYNC RPC must be issued and finished */
1728         CL_FSYNC_ALL   = 3
1729 };
1730
1731 struct cl_io_rw_common {
1732         loff_t      crw_pos;
1733         size_t      crw_count;
1734         int         crw_nonblock;
1735 };
1736
1737 /**
1738  * State for io.
1739  *
1740  * cl_io is shared by all threads participating in this IO (in current
1741  * implementation only one thread advances IO, but parallel IO design and
1742  * concurrent copy_*_user() require multiple threads acting on the same IO. It
1743  * is up to these threads to serialize their activities, including updates to
1744  * mutable cl_io fields.
1745  */
1746 struct cl_io {
1747         /** type of this IO. Immutable after creation. */
1748         enum cl_io_type                ci_type;
1749         /** current state of cl_io state machine. */
1750         enum cl_io_state               ci_state;
1751         /** main object this io is against. Immutable after creation. */
1752         struct cl_object              *ci_obj;
1753         /**
1754          * Upper layer io, of which this io is a part of. Immutable after
1755          * creation.
1756          */
1757         struct cl_io                  *ci_parent;
1758         /** List of slices. Immutable after creation. */
1759         struct list_head                ci_layers;
1760         /** list of locks (to be) acquired by this io. */
1761         struct cl_lockset              ci_lockset;
1762         /** lock requirements, this is just a help info for sublayers. */
1763         enum cl_io_lock_dmd            ci_lockreq;
1764         union {
1765                 struct cl_rd_io {
1766                         struct cl_io_rw_common rd;
1767                 } ci_rd;
1768                 struct cl_wr_io {
1769                         struct cl_io_rw_common wr;
1770                         int                    wr_append;
1771                         int                    wr_sync;
1772                 } ci_wr;
1773                 struct cl_io_rw_common ci_rw;
1774                 struct cl_setattr_io {
1775                         struct ost_lvb           sa_attr;
1776                         unsigned int             sa_attr_flags;
1777                         unsigned int             sa_valid;
1778                         int                      sa_stripe_index;
1779                         const struct lu_fid     *sa_parent_fid;
1780                 } ci_setattr;
1781                 struct cl_data_version_io {
1782                         u64 dv_data_version;
1783                         int dv_flags;
1784                 } ci_data_version;
1785                 struct cl_fault_io {
1786                         /** page index within file. */
1787                         pgoff_t         ft_index;
1788                         /** bytes valid byte on a faulted page. */
1789                         size_t          ft_nob;
1790                         /** writable page? for nopage() only */
1791                         int             ft_writable;
1792                         /** page of an executable? */
1793                         int             ft_executable;
1794                         /** page_mkwrite() */
1795                         int             ft_mkwrite;
1796                         /** resulting page */
1797                         struct cl_page *ft_page;
1798                 } ci_fault;
1799                 struct cl_fsync_io {
1800                         loff_t             fi_start;
1801                         loff_t             fi_end;
1802                         /** file system level fid */
1803                         struct lu_fid     *fi_fid;
1804                         enum cl_fsync_mode fi_mode;
1805                         /* how many pages were written/discarded */
1806                         unsigned int       fi_nr_written;
1807                 } ci_fsync;
1808                 struct cl_ladvise_io {
1809                         __u64                    li_start;
1810                         __u64                    li_end;
1811                         /** file system level fid */
1812                         struct lu_fid           *li_fid;
1813                         enum lu_ladvise_type     li_advice;
1814                         __u64                    li_flags;
1815                 } ci_ladvise;
1816         } u;
1817         struct cl_2queue     ci_queue;
1818         size_t               ci_nob;
1819         int                  ci_result;
1820         unsigned int         ci_continue:1,
1821         /**
1822          * This io has held grouplock, to inform sublayers that
1823          * don't do lockless i/o.
1824          */
1825                              ci_no_srvlock:1,
1826         /**
1827          * The whole IO need to be restarted because layout has been changed
1828          */
1829                              ci_need_restart:1,
1830         /**
1831          * to not refresh layout - the IO issuer knows that the layout won't
1832          * change(page operations, layout change causes all page to be
1833          * discarded), or it doesn't matter if it changes(sync).
1834          */
1835                              ci_ignore_layout:1,
1836         /**
1837          * Check if layout changed after the IO finishes. Mainly for HSM
1838          * requirement. If IO occurs to openning files, it doesn't need to
1839          * verify layout because HSM won't release openning files.
1840          * Right now, only two opertaions need to verify layout: glimpse
1841          * and setattr.
1842          */
1843                              ci_verify_layout:1,
1844         /**
1845          * file is released, restore has to to be triggered by vvp layer
1846          */
1847                              ci_restore_needed:1,
1848         /**
1849          * O_NOATIME
1850          */
1851                              ci_noatime:1;
1852         /**
1853          * Number of pages owned by this IO. For invariant checking.
1854          */
1855         unsigned             ci_owned_nr;
1856 };
1857
1858 /** @} cl_io */
1859
1860 /**
1861  * Per-transfer attributes.
1862  */
1863 struct cl_req_attr {
1864         enum cl_req_type cra_type;
1865         u64              cra_flags;
1866         struct cl_page  *cra_page;
1867         /** Generic attributes for the server consumption. */
1868         struct obdo     *cra_oa;
1869         /** Jobid */
1870         char             cra_jobid[LUSTRE_JOBID_SIZE];
1871 };
1872
1873 enum cache_stats_item {
1874         /** how many cache lookups were performed */
1875         CS_lookup = 0,
1876         /** how many times cache lookup resulted in a hit */
1877         CS_hit,
1878         /** how many entities are in the cache right now */
1879         CS_total,
1880         /** how many entities in the cache are actively used (and cannot be
1881          * evicted) right now */
1882         CS_busy,
1883         /** how many entities were created at all */
1884         CS_create,
1885         CS_NR
1886 };
1887
1888 #define CS_NAMES { "lookup", "hit", "total", "busy", "create" }
1889
1890 /**
1891  * Stats for a generic cache (similar to inode, lu_object, etc. caches).
1892  */
1893 struct cache_stats {
1894         const char      *cs_name;
1895         atomic_t        cs_stats[CS_NR];
1896 };
1897
1898 /** These are not exported so far */
1899 void cache_stats_init (struct cache_stats *cs, const char *name);
1900
1901 /**
1902  * Client-side site. This represents particular client stack. "Global"
1903  * variables should (directly or indirectly) be added here to allow multiple
1904  * clients to co-exist in the single address space.
1905  */
1906 struct cl_site {
1907         struct lu_site          cs_lu;
1908         /**
1909          * Statistical counters. Atomics do not scale, something better like
1910          * per-cpu counters is needed.
1911          *
1912          * These are exported as /proc/fs/lustre/llite/.../site
1913          *
1914          * When interpreting keep in mind that both sub-locks (and sub-pages)
1915          * and top-locks (and top-pages) are accounted here.
1916          */
1917         struct cache_stats      cs_pages;
1918         atomic_t                cs_pages_state[CPS_NR];
1919 };
1920
1921 int  cl_site_init(struct cl_site *s, struct cl_device *top);
1922 void cl_site_fini(struct cl_site *s);
1923 void cl_stack_fini(const struct lu_env *env, struct cl_device *cl);
1924
1925 /**
1926  * Output client site statistical counters into a buffer. Suitable for
1927  * ll_rd_*()-style functions.
1928  */
1929 int cl_site_stats_print(const struct cl_site *site, struct seq_file *m);
1930
1931 /**
1932  * \name helpers
1933  *
1934  * Type conversion and accessory functions.
1935  */
1936 /** @{ */
1937
1938 static inline struct cl_site *lu2cl_site(const struct lu_site *site)
1939 {
1940         return container_of(site, struct cl_site, cs_lu);
1941 }
1942
1943 static inline struct cl_device *lu2cl_dev(const struct lu_device *d)
1944 {
1945         LASSERT(d == NULL || IS_ERR(d) || lu_device_is_cl(d));
1946         return container_of0(d, struct cl_device, cd_lu_dev);
1947 }
1948
1949 static inline struct lu_device *cl2lu_dev(struct cl_device *d)
1950 {
1951         return &d->cd_lu_dev;
1952 }
1953
1954 static inline struct cl_object *lu2cl(const struct lu_object *o)
1955 {
1956         LASSERT(o == NULL || IS_ERR(o) || lu_device_is_cl(o->lo_dev));
1957         return container_of0(o, struct cl_object, co_lu);
1958 }
1959
1960 static inline const struct cl_object_conf *
1961 lu2cl_conf(const struct lu_object_conf *conf)
1962 {
1963         return container_of0(conf, struct cl_object_conf, coc_lu);
1964 }
1965
1966 static inline struct cl_object *cl_object_next(const struct cl_object *obj)
1967 {
1968         return obj ? lu2cl(lu_object_next(&obj->co_lu)) : NULL;
1969 }
1970
1971 static inline struct cl_object_header *luh2coh(const struct lu_object_header *h)
1972 {
1973         return container_of0(h, struct cl_object_header, coh_lu);
1974 }
1975
1976 static inline struct cl_site *cl_object_site(const struct cl_object *obj)
1977 {
1978         return lu2cl_site(obj->co_lu.lo_dev->ld_site);
1979 }
1980
1981 static inline
1982 struct cl_object_header *cl_object_header(const struct cl_object *obj)
1983 {
1984         return luh2coh(obj->co_lu.lo_header);
1985 }
1986
1987 static inline int cl_device_init(struct cl_device *d, struct lu_device_type *t)
1988 {
1989         return lu_device_init(&d->cd_lu_dev, t);
1990 }
1991
1992 static inline void cl_device_fini(struct cl_device *d)
1993 {
1994         lu_device_fini(&d->cd_lu_dev);
1995 }
1996
1997 void cl_page_slice_add(struct cl_page *page, struct cl_page_slice *slice,
1998                        struct cl_object *obj, pgoff_t index,
1999                        const struct cl_page_operations *ops);
2000 void cl_lock_slice_add(struct cl_lock *lock, struct cl_lock_slice *slice,
2001                        struct cl_object *obj,
2002                        const struct cl_lock_operations *ops);
2003 void cl_io_slice_add(struct cl_io *io, struct cl_io_slice *slice,
2004                      struct cl_object *obj, const struct cl_io_operations *ops);
2005 /** @} helpers */
2006
2007 /** \defgroup cl_object cl_object
2008  * @{ */
2009 struct cl_object *cl_object_top (struct cl_object *o);
2010 struct cl_object *cl_object_find(const struct lu_env *env, struct cl_device *cd,
2011                                  const struct lu_fid *fid,
2012                                  const struct cl_object_conf *c);
2013
2014 int  cl_object_header_init(struct cl_object_header *h);
2015 void cl_object_header_fini(struct cl_object_header *h);
2016 void cl_object_put        (const struct lu_env *env, struct cl_object *o);
2017 void cl_object_get        (struct cl_object *o);
2018 void cl_object_attr_lock  (struct cl_object *o);
2019 void cl_object_attr_unlock(struct cl_object *o);
2020 int  cl_object_attr_get(const struct lu_env *env, struct cl_object *obj,
2021                         struct cl_attr *attr);
2022 int  cl_object_attr_update(const struct lu_env *env, struct cl_object *obj,
2023                            const struct cl_attr *attr, unsigned valid);
2024 int  cl_object_glimpse    (const struct lu_env *env, struct cl_object *obj,
2025                            struct ost_lvb *lvb);
2026 int  cl_conf_set          (const struct lu_env *env, struct cl_object *obj,
2027                            const struct cl_object_conf *conf);
2028 int  cl_object_prune      (const struct lu_env *env, struct cl_object *obj);
2029 void cl_object_kill       (const struct lu_env *env, struct cl_object *obj);
2030 int cl_object_getstripe(const struct lu_env *env, struct cl_object *obj,
2031                         struct lov_user_md __user *lum);
2032 int cl_object_fiemap(const struct lu_env *env, struct cl_object *obj,
2033                      struct ll_fiemap_info_key *fmkey, struct fiemap *fiemap,
2034                      size_t *buflen);
2035 int cl_object_layout_get(const struct lu_env *env, struct cl_object *obj,
2036                          struct cl_layout *cl);
2037 loff_t cl_object_maxbytes(struct cl_object *obj);
2038
2039 /**
2040  * Returns true, iff \a o0 and \a o1 are slices of the same object.
2041  */
2042 static inline int cl_object_same(struct cl_object *o0, struct cl_object *o1)
2043 {
2044         return cl_object_header(o0) == cl_object_header(o1);
2045 }
2046
2047 static inline void cl_object_page_init(struct cl_object *clob, int size)
2048 {
2049         clob->co_slice_off = cl_object_header(clob)->coh_page_bufsize;
2050         cl_object_header(clob)->coh_page_bufsize += cfs_size_round(size);
2051         WARN_ON(cl_object_header(clob)->coh_page_bufsize > 512);
2052 }
2053
2054 static inline void *cl_object_page_slice(struct cl_object *clob,
2055                                          struct cl_page *page)
2056 {
2057         return (void *)((char *)page + clob->co_slice_off);
2058 }
2059
2060 /**
2061  * Return refcount of cl_object.
2062  */
2063 static inline int cl_object_refc(struct cl_object *clob)
2064 {
2065         struct lu_object_header *header = clob->co_lu.lo_header;
2066         return atomic_read(&header->loh_ref);
2067 }
2068
2069 /** @} cl_object */
2070
2071 /** \defgroup cl_page cl_page
2072  * @{ */
2073 enum {
2074         CLP_GANG_OKAY = 0,
2075         CLP_GANG_RESCHED,
2076         CLP_GANG_AGAIN,
2077         CLP_GANG_ABORT
2078 };
2079 /* callback of cl_page_gang_lookup() */
2080
2081 struct cl_page *cl_page_find        (const struct lu_env *env,
2082                                      struct cl_object *obj,
2083                                      pgoff_t idx, struct page *vmpage,
2084                                      enum cl_page_type type);
2085 struct cl_page *cl_page_alloc       (const struct lu_env *env,
2086                                      struct cl_object *o, pgoff_t ind,
2087                                      struct page *vmpage,
2088                                      enum cl_page_type type);
2089 void            cl_page_get         (struct cl_page *page);
2090 void            cl_page_put         (const struct lu_env *env,
2091                                      struct cl_page *page);
2092 void            cl_page_print       (const struct lu_env *env, void *cookie,
2093                                      lu_printer_t printer,
2094                                      const struct cl_page *pg);
2095 void            cl_page_header_print(const struct lu_env *env, void *cookie,
2096                                      lu_printer_t printer,
2097                                      const struct cl_page *pg);
2098 struct cl_page *cl_vmpage_page      (struct page *vmpage, struct cl_object *obj);
2099 struct cl_page *cl_page_top         (struct cl_page *page);
2100
2101 const struct cl_page_slice *cl_page_at(const struct cl_page *page,
2102                                        const struct lu_device_type *dtype);
2103
2104 /**
2105  * \name ownership
2106  *
2107  * Functions dealing with the ownership of page by io.
2108  */
2109 /** @{ */
2110
2111 int  cl_page_own        (const struct lu_env *env,
2112                          struct cl_io *io, struct cl_page *page);
2113 int  cl_page_own_try    (const struct lu_env *env,
2114                          struct cl_io *io, struct cl_page *page);
2115 void cl_page_assume     (const struct lu_env *env,
2116                          struct cl_io *io, struct cl_page *page);
2117 void cl_page_unassume   (const struct lu_env *env,
2118                          struct cl_io *io, struct cl_page *pg);
2119 void cl_page_disown     (const struct lu_env *env,
2120                          struct cl_io *io, struct cl_page *page);
2121 int  cl_page_is_owned   (const struct cl_page *pg, const struct cl_io *io);
2122
2123 /** @} ownership */
2124
2125 /**
2126  * \name transfer
2127  *
2128  * Functions dealing with the preparation of a page for a transfer, and
2129  * tracking transfer state.
2130  */
2131 /** @{ */
2132 int  cl_page_prep       (const struct lu_env *env, struct cl_io *io,
2133                          struct cl_page *pg, enum cl_req_type crt);
2134 void cl_page_completion (const struct lu_env *env,
2135                          struct cl_page *pg, enum cl_req_type crt, int ioret);
2136 int  cl_page_make_ready (const struct lu_env *env, struct cl_page *pg,
2137                          enum cl_req_type crt);
2138 int  cl_page_cache_add  (const struct lu_env *env, struct cl_io *io,
2139                          struct cl_page *pg, enum cl_req_type crt);
2140 void cl_page_clip       (const struct lu_env *env, struct cl_page *pg,
2141                          int from, int to);
2142 int  cl_page_cancel     (const struct lu_env *env, struct cl_page *page);
2143 int  cl_page_flush      (const struct lu_env *env, struct cl_io *io,
2144                          struct cl_page *pg);
2145
2146 /** @} transfer */
2147
2148
2149 /**
2150  * \name helper routines
2151  * Functions to discard, delete and export a cl_page.
2152  */
2153 /** @{ */
2154 void    cl_page_discard(const struct lu_env *env, struct cl_io *io,
2155                         struct cl_page *pg);
2156 void    cl_page_delete(const struct lu_env *env, struct cl_page *pg);
2157 int     cl_page_is_vmlocked(const struct lu_env *env,
2158                             const struct cl_page *pg);
2159 void    cl_page_export(const struct lu_env *env,
2160                        struct cl_page *pg, int uptodate);
2161 loff_t  cl_offset(const struct cl_object *obj, pgoff_t idx);
2162 pgoff_t cl_index(const struct cl_object *obj, loff_t offset);
2163 size_t  cl_page_size(const struct cl_object *obj);
2164
2165 void cl_lock_print(const struct lu_env *env, void *cookie,
2166                    lu_printer_t printer, const struct cl_lock *lock);
2167 void cl_lock_descr_print(const struct lu_env *env, void *cookie,
2168                          lu_printer_t printer,
2169                          const struct cl_lock_descr *descr);
2170 /* @} helper */
2171
2172 /**
2173  * Data structure managing a client's cached pages. A count of
2174  * "unstable" pages is maintained, and an LRU of clean pages is
2175  * maintained. "unstable" pages are pages pinned by the ptlrpc
2176  * layer for recovery purposes.
2177  */
2178 struct cl_client_cache {
2179         /**
2180          * # of client cache refcount
2181          * # of users (OSCs) + 2 (held by llite and lov)
2182          */
2183         atomic_t                ccc_users;
2184         /**
2185          * # of threads are doing shrinking
2186          */
2187         unsigned int            ccc_lru_shrinkers;
2188         /**
2189          * # of LRU entries available
2190          */
2191         atomic_long_t           ccc_lru_left;
2192         /**
2193          * List of entities(OSCs) for this LRU cache
2194          */
2195         struct list_head        ccc_lru;
2196         /**
2197          * Max # of LRU entries
2198          */
2199         unsigned long           ccc_lru_max;
2200         /**
2201          * Lock to protect ccc_lru list
2202          */
2203         spinlock_t              ccc_lru_lock;
2204         /**
2205          * Set if unstable check is enabled
2206          */
2207         unsigned int            ccc_unstable_check:1;
2208         /**
2209          * # of unstable pages for this mount point
2210          */
2211         atomic_long_t           ccc_unstable_nr;
2212         /**
2213          * Waitq for awaiting unstable pages to reach zero.
2214          * Used at umounting time and signaled on BRW commit
2215          */
2216         wait_queue_head_t       ccc_unstable_waitq;
2217 };
2218 /**
2219  * cl_cache functions
2220  */
2221 struct cl_client_cache *cl_cache_init(unsigned long lru_page_max);
2222 void cl_cache_incref(struct cl_client_cache *cache);
2223 void cl_cache_decref(struct cl_client_cache *cache);
2224
2225 /** @} cl_page */
2226
2227 /** \defgroup cl_lock cl_lock
2228  * @{ */
2229 int cl_lock_request(const struct lu_env *env, struct cl_io *io,
2230                     struct cl_lock *lock);
2231 int cl_lock_init(const struct lu_env *env, struct cl_lock *lock,
2232                  const struct cl_io *io);
2233 void cl_lock_fini(const struct lu_env *env, struct cl_lock *lock);
2234 const struct cl_lock_slice *cl_lock_at(const struct cl_lock *lock,
2235                                        const struct lu_device_type *dtype);
2236 void cl_lock_release(const struct lu_env *env, struct cl_lock *lock);
2237
2238 int cl_lock_enqueue(const struct lu_env *env, struct cl_io *io,
2239                     struct cl_lock *lock, struct cl_sync_io *anchor);
2240 void cl_lock_cancel(const struct lu_env *env, struct cl_lock *lock);
2241
2242 /** @} cl_lock */
2243
2244 /** \defgroup cl_io cl_io
2245  * @{ */
2246
2247 int   cl_io_init         (const struct lu_env *env, struct cl_io *io,
2248                           enum cl_io_type iot, struct cl_object *obj);
2249 int   cl_io_sub_init     (const struct lu_env *env, struct cl_io *io,
2250                           enum cl_io_type iot, struct cl_object *obj);
2251 int   cl_io_rw_init      (const struct lu_env *env, struct cl_io *io,
2252                           enum cl_io_type iot, loff_t pos, size_t count);
2253 int   cl_io_loop         (const struct lu_env *env, struct cl_io *io);
2254
2255 void  cl_io_fini         (const struct lu_env *env, struct cl_io *io);
2256 int   cl_io_iter_init    (const struct lu_env *env, struct cl_io *io);
2257 void  cl_io_iter_fini    (const struct lu_env *env, struct cl_io *io);
2258 int   cl_io_lock         (const struct lu_env *env, struct cl_io *io);
2259 void  cl_io_unlock       (const struct lu_env *env, struct cl_io *io);
2260 int   cl_io_start        (const struct lu_env *env, struct cl_io *io);
2261 void  cl_io_end          (const struct lu_env *env, struct cl_io *io);
2262 int   cl_io_lock_add     (const struct lu_env *env, struct cl_io *io,
2263                           struct cl_io_lock_link *link);
2264 int   cl_io_lock_alloc_add(const struct lu_env *env, struct cl_io *io,
2265                            struct cl_lock_descr *descr);
2266 int   cl_io_submit_rw    (const struct lu_env *env, struct cl_io *io,
2267                           enum cl_req_type iot, struct cl_2queue *queue);
2268 int   cl_io_submit_sync  (const struct lu_env *env, struct cl_io *io,
2269                           enum cl_req_type iot, struct cl_2queue *queue,
2270                           long timeout);
2271 int   cl_io_commit_async (const struct lu_env *env, struct cl_io *io,
2272                           struct cl_page_list *queue, int from, int to,
2273                           cl_commit_cbt cb);
2274 int   cl_io_read_ahead   (const struct lu_env *env, struct cl_io *io,
2275                           pgoff_t start, struct cl_read_ahead *ra);
2276 void  cl_io_rw_advance   (const struct lu_env *env, struct cl_io *io,
2277                           size_t nob);
2278 int   cl_io_cancel       (const struct lu_env *env, struct cl_io *io,
2279                           struct cl_page_list *queue);
2280 int   cl_io_is_going     (const struct lu_env *env);
2281
2282 /**
2283  * True, iff \a io is an O_APPEND write(2).
2284  */
2285 static inline int cl_io_is_append(const struct cl_io *io)
2286 {
2287         return io->ci_type == CIT_WRITE && io->u.ci_wr.wr_append;
2288 }
2289
2290 static inline int cl_io_is_sync_write(const struct cl_io *io)
2291 {
2292         return io->ci_type == CIT_WRITE && io->u.ci_wr.wr_sync;
2293 }
2294
2295 static inline int cl_io_is_mkwrite(const struct cl_io *io)
2296 {
2297         return io->ci_type == CIT_FAULT && io->u.ci_fault.ft_mkwrite;
2298 }
2299
2300 /**
2301  * True, iff \a io is a truncate(2).
2302  */
2303 static inline int cl_io_is_trunc(const struct cl_io *io)
2304 {
2305         return io->ci_type == CIT_SETATTR &&
2306                 (io->u.ci_setattr.sa_valid & ATTR_SIZE);
2307 }
2308
2309 struct cl_io *cl_io_top(struct cl_io *io);
2310
2311 void cl_io_print(const struct lu_env *env, void *cookie,
2312                  lu_printer_t printer, const struct cl_io *io);
2313
2314 #define CL_IO_SLICE_CLEAN(foo_io, base)                                 \
2315 do {                                                                    \
2316         typeof(foo_io) __foo_io = (foo_io);                             \
2317                                                                         \
2318         CLASSERT(offsetof(typeof(*__foo_io), base) == 0);               \
2319         memset(&__foo_io->base + 1, 0,                                  \
2320                (sizeof *__foo_io) - sizeof __foo_io->base);             \
2321 } while (0)
2322
2323 /** @} cl_io */
2324
2325 /** \defgroup cl_page_list cl_page_list
2326  * @{ */
2327
2328 /**
2329  * Last page in the page list.
2330  */
2331 static inline struct cl_page *cl_page_list_last(struct cl_page_list *plist)
2332 {
2333         LASSERT(plist->pl_nr > 0);
2334         return list_entry(plist->pl_pages.prev, struct cl_page, cp_batch);
2335 }
2336
2337 static inline struct cl_page *cl_page_list_first(struct cl_page_list *plist)
2338 {
2339         LASSERT(plist->pl_nr > 0);
2340         return list_entry(plist->pl_pages.next, struct cl_page, cp_batch);
2341 }
2342
2343 /**
2344  * Iterate over pages in a page list.
2345  */
2346 #define cl_page_list_for_each(page, list)                               \
2347         list_for_each_entry((page), &(list)->pl_pages, cp_batch)
2348
2349 /**
2350  * Iterate over pages in a page list, taking possible removals into account.
2351  */
2352 #define cl_page_list_for_each_safe(page, temp, list)                    \
2353         list_for_each_entry_safe((page), (temp), &(list)->pl_pages, cp_batch)
2354
2355 void cl_page_list_init   (struct cl_page_list *plist);
2356 void cl_page_list_add    (struct cl_page_list *plist, struct cl_page *page);
2357 void cl_page_list_move   (struct cl_page_list *dst, struct cl_page_list *src,
2358                           struct cl_page *page);
2359 void cl_page_list_move_head(struct cl_page_list *dst, struct cl_page_list *src,
2360                           struct cl_page *page);
2361 void cl_page_list_splice (struct cl_page_list *list,
2362                           struct cl_page_list *head);
2363 void cl_page_list_del    (const struct lu_env *env,
2364                           struct cl_page_list *plist, struct cl_page *page);
2365 void cl_page_list_disown (const struct lu_env *env,
2366                           struct cl_io *io, struct cl_page_list *plist);
2367 int  cl_page_list_own    (const struct lu_env *env,
2368                           struct cl_io *io, struct cl_page_list *plist);
2369 void cl_page_list_assume (const struct lu_env *env,
2370                           struct cl_io *io, struct cl_page_list *plist);
2371 void cl_page_list_discard(const struct lu_env *env,
2372                           struct cl_io *io, struct cl_page_list *plist);
2373 void cl_page_list_fini   (const struct lu_env *env, struct cl_page_list *plist);
2374
2375 void cl_2queue_init     (struct cl_2queue *queue);
2376 void cl_2queue_add      (struct cl_2queue *queue, struct cl_page *page);
2377 void cl_2queue_disown   (const struct lu_env *env,
2378                          struct cl_io *io, struct cl_2queue *queue);
2379 void cl_2queue_assume   (const struct lu_env *env,
2380                          struct cl_io *io, struct cl_2queue *queue);
2381 void cl_2queue_discard  (const struct lu_env *env,
2382                          struct cl_io *io, struct cl_2queue *queue);
2383 void cl_2queue_fini     (const struct lu_env *env, struct cl_2queue *queue);
2384 void cl_2queue_init_page(struct cl_2queue *queue, struct cl_page *page);
2385
2386 /** @} cl_page_list */
2387
2388 void cl_req_attr_set(const struct lu_env *env, struct cl_object *obj,
2389                      struct cl_req_attr *attr);
2390
2391 /** \defgroup cl_sync_io cl_sync_io
2392  * @{ */
2393
2394 /**
2395  * Anchor for synchronous transfer. This is allocated on a stack by thread
2396  * doing synchronous transfer, and a pointer to this structure is set up in
2397  * every page submitted for transfer. Transfer completion routine updates
2398  * anchor and wakes up waiting thread when transfer is complete.
2399  */
2400 struct cl_sync_io {
2401         /** number of pages yet to be transferred. */
2402         atomic_t                csi_sync_nr;
2403         /** error code. */
2404         int                     csi_sync_rc;
2405         /** barrier of destroy this structure */
2406         atomic_t                csi_barrier;
2407         /** completion to be signaled when transfer is complete. */
2408         wait_queue_head_t       csi_waitq;
2409         /** callback to invoke when this IO is finished */
2410         void                    (*csi_end_io)(const struct lu_env *,
2411                                               struct cl_sync_io *);
2412 };
2413
2414 void cl_sync_io_init(struct cl_sync_io *anchor, int nr,
2415                      void (*end)(const struct lu_env *, struct cl_sync_io *));
2416 int  cl_sync_io_wait(const struct lu_env *env, struct cl_sync_io *anchor,
2417                      long timeout);
2418 void cl_sync_io_note(const struct lu_env *env, struct cl_sync_io *anchor,
2419                      int ioret);
2420 void cl_sync_io_end(const struct lu_env *env, struct cl_sync_io *anchor);
2421
2422 /** @} cl_sync_io */
2423
2424 /** \defgroup cl_env cl_env
2425  *
2426  * lu_env handling for a client.
2427  *
2428  * lu_env is an environment within which lustre code executes. Its major part
2429  * is lu_context---a fast memory allocation mechanism that is used to conserve
2430  * precious kernel stack space. Originally lu_env was designed for a server,
2431  * where
2432  *
2433  *     - there is a (mostly) fixed number of threads, and
2434  *
2435  *     - call chains have no non-lustre portions inserted between lustre code.
2436  *
2437  * On a client both these assumtpion fails, because every user thread can
2438  * potentially execute lustre code as part of a system call, and lustre calls
2439  * into VFS or MM that call back into lustre.
2440  *
2441  * To deal with that, cl_env wrapper functions implement the following
2442  * optimizations:
2443  *
2444  *     - allocation and destruction of environment is amortized by caching no
2445  *     longer used environments instead of destroying them;
2446  *
2447  * \see lu_env, lu_context, lu_context_key
2448  * @{ */
2449
2450 struct lu_env *cl_env_get(__u16 *refcheck);
2451 struct lu_env *cl_env_alloc(__u16 *refcheck, __u32 tags);
2452 void cl_env_put(struct lu_env *env, __u16 *refcheck);
2453 unsigned cl_env_cache_purge(unsigned nr);
2454 struct lu_env *cl_env_percpu_get(void);
2455 void cl_env_percpu_put(struct lu_env *env);
2456
2457 /** @} cl_env */
2458
2459 /*
2460  * Misc
2461  */
2462 void cl_attr2lvb(struct ost_lvb *lvb, const struct cl_attr *attr);
2463 void cl_lvb2attr(struct cl_attr *attr, const struct ost_lvb *lvb);
2464
2465 struct cl_device *cl_type_setup(const struct lu_env *env, struct lu_site *site,
2466                                 struct lu_device_type *ldt,
2467                                 struct lu_device *next);
2468 /** @} clio */
2469
2470 int cl_global_init(void);
2471 void cl_global_fini(void);
2472
2473 #endif /* _LINUX_CL_OBJECT_H */