1    	/*
2    	 * vim:noexpandtab:shiftwidth=8:tabstop=8:
3    	 *
4    	 * Copyright (C) Panasas Inc., 2011
5    	 * Author: Jim Lieb jlieb@panasas.com
6    	 *
7    	 * contributeur : Philippe DENIEL   philippe.deniel@cea.fr
8    	 *                Thomas LEIBOVICI  thomas.leibovici@cea.fr
9    	 *
10   	 *
11   	 * This program is free software; you can redistribute it and/or
12   	 * modify it under the terms of the GNU Lesser General Public
13   	 * License as published by the Free Software Foundation; either
14   	 * version 3 of the License, or (at your option) any later version.
15   	 *
16   	 * This program is distributed in the hope that it will be useful,
17   	 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18   	 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19   	 * Lesser General Public License for more details.
20   	 *
21   	 * You should have received a copy of the GNU Lesser General Public
22   	 * License along with this library; if not, write to the Free Software
23   	 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
24   	 * 02110-1301 USA
25   	 *
26   	 * -------------
27   	 */
28   	
29   	/**
30   	 * @defgroup FSAL File-System Abstraction Layer
31   	 * @{
32   	 */
33   	
34   	/**
35   	 * @file fsal_api.h
36   	 * @author Jim Lieb <jlieb@panasas.com>
37   	 * @brief The object-oriented FSAL API
38   	 */
39   	
40   	#ifndef FSAL_API
41   	#define FSAL_API
42   	
43   	#include "fsal_types.h"
44   	#include "fsal_pnfs.h"
45   	#include "sal_shared.h"
46   	#include "config_parsing.h"
47   	#include "avltree.h"
48   	#include "abstract_atomic.h"
49   	
50   	/**
51   	** Forward declarations to resolve circular dependency conflicts
52   	*/
53   	struct gsh_client;
54   	struct gsh_export;
55   	struct fsal_up_vector;		/* From fsal_up.h */
56   	struct state_t;
57   	
58   	/**
59   	 * @page newapi New FSAL API
60   	 *
61   	 * @section structs Public and Private Data Structures
62   	 *
63   	 * Shared FSAL data structures have two definitions, one that is
64   	 * global and passed around by the core, the other private which
65   	 * included the global definition within it.
66   	 *
67   	 * All these data structures are passed back to the core with the
68   	 * global pointer and dereferenced with container_of within the FSAL
69   	 * itself like so:
70   	 *
71   	 * @code{.c}
72   	 *
73   	 * struct private_obj_handle
74   	 * {
75   	 *         [private stuff]
76   	 *         struct fsal_obj_handle *pub;
77   	 * }
78   	 *
79   	 * fsal_getattr(struct fsal_obj_handle handle_pub)
80   	 * {
81   	 *         struct private_obj_handle *handle;
82   	 *
83   	 *         handle = container_of(handle_pub,
84   	 *                               struct private_obj_handle, pub);
85   	 *         [ do stuff ]
86   	 * }
87   	 * @endcode
88   	 *
89   	 * The @c container_of macro takes the public pointer/handle @c
90   	 * handle_pub which is indicated as the element @c pub of structure
91   	 * type @c private_obj_handle.  Throughout the function, where private
92   	 * elements are dereferenced, the @c handle pointer is used.  The @c
93   	 * handle_pub pointer is used in the public case.
94   	 *
95   	 * @section usage Object usage
96   	 *
97   	 * Mutex locks and reference counts are used to manage both concurrent
98   	 * usage and state.  The reference counts are use to determine when
99   	 * the object is "free".  Current use is for managing ref counts and
100  	 * lists.  This will be expanded, though many cases are already
101  	 * handled by the locks in Cache inode.
102  	 *
103  	 * Since we cannot create objects out of thin air, there is an order
104  	 * based on one object being the "context" in which the other is
105  	 * created.  In other words, a @c fsal_export is created from the @c
106  	 * fsal_module that connects it to the backing store (filesystem). The
107  	 * same applies to a @c fsal_obj_handle that only makes sense for a
108  	 * specific 'fsal_export'.
109  	 *
110  	 * When an object is created, it is returned with a reference already
111  	 * taken.  The callee of the creating method must then either keep a
112  	 * persistent reference to it or @c put it back.  For example, a @c
113  	 * fsal_export gets created for each export in the configuration.  A
114  	 * pointer to it gets saved in @c gsh_export and it has a reference
115  	 * to reflect this.  It is now safe to use it to do a @c lookup which
116  	 * will return a @c fsal_obj_handle which can then be kept in a cache
117  	 * inode entry.  If we had done a @c put on the export, it could be
118  	 * freed at any point and make a @c lookup using it unsafe.
119  	 *
120  	 * In addition to a reference count, object that create other objects
121  	 * have a list of all the objects they create.  This serves two
122  	 * purposes. The obvious case is to keep the object "busy" until all
123  	 * of its children are freed.  Second, it provides a means to visit
124  	 * all of the objects it creates.
125  	 *
126  	 * Every object has a pointer to its parent.  This is used for such
127  	 * things as managing the object list and for calling methods on the
128  	 * parent.
129  	 *
130  	 * @section versioning Versioning
131  	 *
132  	 * One intent in this API is to be able to support fsals that are built
133  	 * out-of-tree and possibly out of synch with the core of Ganesha.  This
134  	 * is managed by version numbers in this file that are validated at load
135  	 * time for the fsal.  There are major and minor version numbers which are
136  	 * monotonically increasing numbers ( V1 < V2 means V2 is newer).
137  	 *
138  	 * API guarantee:
139  	 *
140  	 * * If major version numbers differ, the fsal will not be loaded because
141  	 *   the api has changed enough to make it unsafe.
142  	 *
143  	 * * If the major versions are equal, the minor version determines loadability.
144  	 *
145  	 *   - A fsal that is older than the Ganesha core can safely load and run.
146  	 *
147  	 *   - A fsal that is newer than the Ganesha core is not safe and will not
148  	 *     be loaded.
149  	 *
150  	 *
151  	 * @section vector Operation Vectors
152  	 *
153  	 * Each structure carries with it an @c ops pointer.  Default
154  	 * operation vectors are created at FSAL moduel initialziation time,
155  	 * and may be overridden there.  Individual exports or handles may
156  	 * have different operations vectors, but they should all be derived
157  	 * from the module operations vector.
158  	 *
159  	 *	This vector is used to access methods e.g.:
160  	 *
161  	 * @code{.c}
162  	 * exp_hdl->exp_ops.lookup(exp_hdl, name, ...);
163  	 * @endcode
164  	 *
165  	 * Note that exp_hdl is used to dereference the method and it is also
166  	 * *always* the first argument to the method/function.  Think of it as
167  	 * the 'this' argument.
168  	 *
169  	 * @section Operation Context
170  	 *
171  	 * Protocol operations have lots of state such as user creds, the
172  	 * export currently in use etc.  Rather than pass all this down the
173  	 * stack we take advantage of the design decision that a protocol
174  	 * operation runs to completion in the thread that dequeued the
175  	 * request from the RPC.  All of the operation state (other than
176  	 * some intermediate results passed as function args) are pointed
177  	 * to by the thread local 'op_ctx'.  This will always point to a
178  	 * valid and initialized 'struct req_op_context'.
179  	 *
180  	 *	Method code can reference through 'op_ctx' e.g.
181  	 *
182  	 * @code{.c}
183  	 * if (op_ctx->req_type == 9P) { ... }
184  	 * @endcode
185  	 *
186  	 */
187  	
188  	/**
189  	 * @page handles File-Handles and You
190  	 *
191  	 * Overview
192  	 * ========
193  	 *
194  	 * In the FSAL, file handles can take four forms.  There is the full,
195  	 * internal handle structure, compose of the @c fsal_obj_handle and
196  	 * the FSAL-private structure that contains it.
197  	 *
198  	 * There is the wire-handle, the FSAL-generated portion of the
199  	 * file handles exchanged between Ganesha and its clients through the
200  	 * FS protocol.  The wire-handle should contain everything necessary
201  	 * to find and use the file even if the file has been completely
202  	 * purged from cache or Ganesha has restarted from nothing.  There may
203  	 * be multiple wire-handles per @c fsal_obj_handle.  The wire-handle
204  	 * is produced by the @c handle_to_wire method on @c fsal_obj_handle.
205  	 * FSALs can produce big endian or little endian wire-handles depending
206  	 * on the architecture.
207  	 *
208  	 * A host-handle is a verion of the wire handle in host endian format.  It is
209  	 * produced from wire-handle by @c wire_to_host to the host's native endian
210  	 * type.  @c fsal_export operation @c create_handle produces a new @c
211  	 * fsal_obj_handle from a host-handle.
212  	 *
213  	 * Finally, there is the handle-key, a portion of the handle that contains
214  	 * all and only information that uniquely identifies the object within
215  	 * the entire FSAL (it is insufficient if it only identifies it within
216  	 * the export or within a filesystem.)  There are two functions that
217  	 * generate a handle-key, one is the @c host_to_key method on @c
218  	 * fsal_export.  It is used to get the key from a host-handle so that
219  	 * it can be looked up in the cache.  The other is @c handle_to_key on
220  	 * @c fsal_obj_handle.  This is used after lookup or some other
221  	 * operation that produces a @c fsal_obj_handle so that it can be
222  	 * stored or looked up in the cache.
223  	 *
224  	 * The invariant to be maintained is that given an @c fsal_obj_handle,
225  	 * obj_hdl, exp_ops.host_to_key(wire_to_host(handle_to_wire(obj_hdl)))
226  	 * is equal to obj_ops->handle_to_key(obj_hdl).
227  	 *
228  	 * History and Details
229  	 * ===================
230  	 *
231  	 * The terminology is confusing here.  The old function names were
232  	 * kept (up to a point), but the semantics differ in ways both subtle
233  	 * and catastrophic. Making matters worse, that the first FSAL written
234  	 * was VFS, where the internal @c file_handle for the syscalls is the
235  	 * whole of the key, opaque, and syscall arg.  This does not imply any
236  	 * equivalence.
237  	 *
238  	 * In the old regime, the only place available to store _anything_ was
239  	 * the handle array in @c cache_entry_t.  People overloaded it with
240  	 * all kinds of rubbish as a result, and the wire-handle, the
241  	 * handle-key, and other stuff get mushed together.  To sort things
242  	 * out,
243  	 *
244  	 * 1. The wire-handle opaque _must_ be enough to re-acquire the cache
245  	 *    entry and its associated @c fsal_obj_handle.  Other than that,
246  	 *    it doesn't matter a whit. The client treats the whole protocol
247  	 *    handle (including what is in the opaque) as an opaque token.
248  	 *
249  	 * 2. The purpose of the @c export_id in the protocol "handle" is to
250  	 *    locate the FSAL that knows what is inside the opaque.  The @c
251  	 *    wire_to_host is an export method for that purpose.  It should
252  	 *    be able to take the wire-handle opaque and translate it into
253  	 *    a host-handle. handle-key should be derived from @c host_to_key
254  	 *    that MDCACHE can use to find an entry.
255  	 *
256  	 * 3. OBSOLETE - cache_inode_get takes an fh_desc argument which is not a
257  	 *    handle but a _key_.  It is used to generate the hash and to do
258  	 *    the secondary key compares.  That is all it is used for.  The
259  	 *    end result _must_ be a cache entry and its associated
260  	 *    @c fsal_obj_handle. See how @c cache_inode_get transitions to
261  	 *    cache_inode_new to see how this works.
262  	 *
263  	 * 4. The @c handle_to_key method, a @c fsal_obj_handle method,
264  	 *    generates a key for the MDCACHE hash table from the contents
265  	 *    of the @c fsal_obj_handle.  It is an analogue of fsal export
266  	 *    @c host_to_key method. Note where it is called to see why it is
267  	 *    there.
268  	 *
269  	 * 5. The @c handle_to_wire method is similar in scope but it is the
270  	 *    inverse of @c wire_to_host.  It's job is to fill in the opaque
271  	 *    part of a protocol handle.  Note that it gets passed a @c gsh_buffdesc
272  	 *    that describes the full opaque storage in whatever protocol
273  	 *    specific structure is used.  It's job is to put whatever it
274  	 *    takes into the opaque so the second and third items in this list
275  	 *    work.
276  	 *
277  	 * 6. Unlike the old API, a @c fsal_obj_handle is part of a FSAL
278  	 *    private structure for the object.  Note that there is no handle
279  	 *    member of this public structure.  The bits necessary to both
280  	 *    create a wire handle and use a filesystem handle go into this
281  	 *    private structure. You can put whatever is required into the
282  	 *    private part.  Since both @c fsal_export and @c fsal_obj_handle
283  	 *    have private object storage, you could even do things like have
284  	 *    a container anchored in the export object that maps the
285  	 *    FSAL-external handle to the filesystem data needed to talk to
286  	 *    the filesystem.  If you need more info to deal with handles
287  	 *    differing due to hard-links, this is where you would put
288  	 *    it.  You would also have some other context in this private data
289  	 *    to do the right thing.  Just make sure there is a way to
290  	 *    disambiguate the multiple cases.  We do have to observe UNIX
291  	 *    semantics here.
292  	 *
293  	 * The upper layers don't care about the private handle data.  All
294  	 * they want is to be able to get something out from the object
295  	 * (result of a lookup) so it can find the object again later.  The
296  	 * obvious case is what you describe in @c nfs[34]_FhandleToCache.  These
297  	 * various methods make that happen.
298  	 *
299  	 */
300  	
301  	/**
302  	 * @brief Major Version
303  	 *
304  	 * Increment this whenever any part of the existing API is changed,
305  	 * e.g.  the argument list changed or a method is removed.
306  	 */
307  	
308  	#define FSAL_MAJOR_VERSION 8
309  	
310  	/**
311  	 * @brief Minor Version
312  	 *
313  	 * Increment this whenever a new method is appended to the m_ops vector.
314  	 * The remainder of the API is unchanged.
315  	 *
316  	 * If the major version is incremented, reset the minor to 0 (zero).
317  	 *
318  	 * If new members are appended to struct req_op_context (following its own
319  	 * rules), increment the minor version
320  	 */
321  	
322  	#define FSAL_MINOR_VERSION 0
323  	
324  	/* Forward references for object methods */
325  	
326  	struct fsal_module;
327  	struct fsal_export;
328  	struct fsal_obj_handle;
329  	struct fsal_filesystem;
330  	struct fsal_pnfs_ds;
331  	struct fsal_pnfs_ds_ops;
332  	struct fsal_ds_handle;
333  	struct fsal_dsh_ops;
334  	
335  	#ifndef SEEK_SET
336  	#define SEEK_SET 0
337  	#endif
338  	#ifndef SEEK_CUR
339  	#define SEEK_CUR 1
340  	#endif
341  	#ifndef SEEK_END
342  	#define SEEK_END 2
343  	#endif
344  	#ifndef SEEK_DATA
345  	#define SEEK_DATA 3
346  	#endif
347  	#ifndef SEEK_HOLE
348  	#define SEEK_HOLE 4
349  	#endif
350  	
351  	struct io_info {
352  		contents io_content;
353  		uint32_t io_advise;
354  		bool_t   io_eof;
355  	};
356  	
357  	struct io_hints {
358  		offset4  offset;
359  		length4  count;
360  		uint32_t hints;
361  	};
362  	
363  	/**
364  	 * @brief request op context
365  	 *
366  	 * This is created early in the operation with the context of the
367  	 * operation.  The difference between "context" and request parameters
368  	 * or arguments is that the context is derived information such as
369  	 * the resolved credentials, socket (network and client host) data
370  	 * and other bits of environment associated with the request.  It gets
371  	 * passed down the call chain only as far as it needs to go for the op
372  	 * i.e. don't put it in the function/method proto "just because".
373  	 *
374  	 * The lifetime of this structure and all the data it points to is the
375  	 * operation for V2,3 and the compound for V4+.  All elements and what
376  	 * they point to are invariant for the lifetime.
377  	 *
378  	 * NOTE: This is an across-the-api shared structure.  It must survive with
379  	 *       older consumers of its contents.  Future development can change
380  	 *       this struct so long as it follows the rules:
381  	 *
382  	 *       1. New elements are appended at the end, never inserted in the middle.
383  	 *
384  	 *       2. This structure _only_ contains pointers and simple scalar values.
385  	 *
386  	 *       3. Changing an already defined struct pointer is strictly not allowed.
387  	 *
388  	 *       4. This struct is always passed by reference, never by value.
389  	 *
390  	 *       5. This struct is never copied/saved.
391  	 *
392  	 *       6. Code changes are first introduced in the core.  Assume the fsal
393  	 *          module does not know and the code will still do the right thing.
394  	 */
395  	
396  	struct req_op_context {
397  		struct user_cred *creds;	/*< resolved user creds from request */
398  		struct user_cred original_creds;	/*< Saved creds */
399  		struct group_data *caller_gdata;
400  		gid_t *caller_garray_copy;	/*< Copied garray from AUTH_SYS */
401  		gid_t *managed_garray_copy;	/*< Copied garray from managed gids */
402  		int	cred_flags;		/* Various cred flags */
403  		sockaddr_t *caller_addr;	/*< IP connection info */
404  		const uint64_t *clientid;	/*< Client ID of caller, NULL if
405  						   unknown/not applicable. */
406  		uint32_t nfs_vers;	/*< NFS protocol version of request */
407  		uint32_t nfs_minorvers;	/*< NFSv4 minor version */
408  		uint32_t req_type;	/*< request_type NFS | 9P */
409  		struct gsh_client *client;	/*< client host info including stats */
410  		struct gsh_export *ctx_export;	/*< current export */
411  		struct fsal_export *fsal_export;	/*< current fsal export */
412  		struct export_perms *export_perms;	/*< Effective export perms */
413  		nsecs_elapsed_t start_time;	/*< start time of this op/request */
414  		void *fsal_private;		/*< private for FSAL use */
415  		struct fsal_module *fsal_module;	/*< current fsal module */
416  		struct fsal_pnfs_ds *fsal_pnfs_ds;	/*< current pNFS DS */
417  		/* add new context members here */
418  	};
419  	
420  	/**
421  	 * @brief FSAL module methods
422  	 */
423  	
424  	struct fsal_ops {
425  	/**@{*/
426  	/**
427  	 * Base methods for loading and lifetime.
428  	 */
429  	
430  	/**
431  	 * @brief Unload a module
432  	 *
433  	 * This function unloads the FSL module.  It should not be overridden.
434  	 *
435  	 * @param[in] fsal_hdl The module to unload.
436  	 *
437  	 * @retval 0     On success.
438  	 * @retval EBUSY If there are outstanding references or exports.
439  	 */
440  		int (*unload)(struct fsal_module *fsal_hdl);
441  	
442  	/**@}*/
443  	
444  	/**@{*/
445  	/**
446  	 * Subclass/instance methods in each fsal
447  	 */
448  	
449  	/**
450  	 * @brief Initialize the configuration
451  	 *
452  	 * Given the root of the Ganesha configuration structure, initialize
453  	 * the FSAL parameters.
454  	 *
455  	 * @param[in] fsal_hdl      The FSAL module
456  	 * @param[in] config_struct Parsed ganesha configuration file
457  	 * @param[out]err_type      config error processing state
458  	 *
459  	 * @return FSAL status.
460  	 */
461  		 fsal_status_t (*init_config)(struct fsal_module *fsal_hdl,
462  					      config_file_t config_struct,
463  					      struct config_error_type *err_type);
464  	/**
465  	 * @brief Dump configuration
466  	 *
467  	 * This function dumps a human readable representation of the FSAL
468  	 * configuration.
469  	 *
470  	 * @param[in] fsal_hdl The FSAL module.
471  	 * @param[in] log_fd   File descriptor to which to output the dump
472  	 */
473  		void (*dump_config)(struct fsal_module *fsal_hdl, int log_fd);
474  	
475  	/**
476  	 * @brief Create a new export
477  	 *
478  	 * This function creates a new export in the FSAL using the supplied
479  	 * path and options.  The function is expected to allocate its own
480  	 * export (the full, private structure).  It must then initialize the
481  	 * public portion like so:
482  	 *
483  	 * @code{.c}
484  	 *         fsal_export_init(&private_export_handle->pub);
485  	 * @endcode
486  	 *
487  	 * After doing other private initialization, it must attach the export
488  	 * to the module, like so:
489  	 *
490  	 *
491  	 * @code{.c}
492  	 *         fsal_attach_export(fsal_hdl,
493  	 *                            &private_export->pub.exports);
494  	 *
495  	 * @endcode
496  	 *
497  	 * And create the parent link with:
498  	 *
499  	 * @code{.c}
500  	 * private_export->pub.fsal = fsal_hdl;
501  	 * @endcode
502  	 *
503  	 * @note This seems like something that fsal_attach_export should
504  	 * do. -- ACE.
505  	 *
506  	 * @param[in]     fsal_hdl    FSAL module
507  	 * @param[in]     parse_node  opaque pointer to parse tree node for
508  	 *                            export options to be passed to
509  	 *                            load_config_from_node
510  	 * @param[out]    err_type    config proocessing error reporting
511  	 * @param[in]     up_ops      Upcall ops
512  	 *
513  	 * @return FSAL status.
514  	 */
515  		 fsal_status_t (*create_export)(struct fsal_module *fsal_hdl,
516  						void *parse_node,
517  						struct config_error_type *err_type,
518  						const struct fsal_up_vector *up_ops);
519  	
520  	/**
521  	 * @brief Update an existing export
522  	 *
523  	 * This will result in a temporary fsal_export being created, and built into
524  	 * a stacked export.
525  	 *
526  	 * On entry, op_ctx has the original gsh_export and no fsal_export.
527  	 *
528  	 * The caller passes the original fsal_export, as well as the new super_export's
529  	 * FSAL when there is a stacked export. This will allow the underlying export to
530  	 * validate that the stacking has not changed.
531  	 *
532  	 * This function does not actually create a new fsal_export, the only purpose is
533  	 * to validate and update the config.
534  	 *
535  	 * @param[in]     fsal_hdl         FSAL module
536  	 * @param[in]     parse_node       opaque pointer to parse tree node for
537  	 *                                 export options to be passed to
538  	 *                                 load_config_from_node
539  	 * @param[out]    err_type         config proocessing error reporting
540  	 * @param[in]     original         The original export that is being updated
541  	 * @param[in]     updated_super    The updated super_export's FSAL
542  	 *
543  	 * @return FSAL status.
544  	 */
545  		 fsal_status_t (*update_export)(struct fsal_module *fsal_hdl,
546  						void *parse_node,
547  						struct config_error_type *err_type,
548  						struct fsal_export *original,
549  						struct fsal_module *updated_super);
550  	
551  	/**
552  	 * @brief Minimal emergency cleanup on error
553  	 *
554  	 * This method is called only in the event of a catastrophic
555  	 * failure. Currently, it will be called if some detail of the orderly
556  	 * shutdown fails, so that FSALs will have the opportunity to leave
557  	 * their underlying filesystems in a consistent state. It may at some
558  	 * later time be called in the event of a crash. The majority of FSALs
559  	 * will have no need to implement this call and should not do so.
560  	 *
561  	 * This function should, if implemented:
562  	 *
563  	 * 1. Do the bare minimum necessary to allow access to the each
564  	 * underlying filesystem it serves. (the equivalent of a clean
565  	 * unmount, so that a future instance of Ganesha or other tool can
566  	 * mount the filesystem without difficulty.) How the FSAL defines
567  	 * 'underlying filesystem' is FSAL specific. The FSAL handle itself
568  	 * has a list of attached exports and that can be traversed if
569  	 * suitable.
570  	 *
571  	 * 2. It /must not/ take any mutices, reader-writer locks, spinlocks,
572  	 * sleep on any condition variables, or similar. Since other threads
573  	 * may have crashed or been cancelled, locks may be left held,
574  	 * overwritten with random garbage, or be similarly awful. The point
575  	 * is to shut down cleanly, and you can't shut down cleanly if you're
576  	 * hung. This does not create a race condition, since other threads in
577  	 * Ganesha will have been cancelled by this point.
578  	 *
579  	 * 3. If it is at all possible to avoid, do not allocate memory on the
580  	 * heap or use other services that require the user space to be in a
581  	 * consistent state. If this is called from a crash handler, the Arena
582  	 * may be corrupt. If you know that your FSAL *will* require memory,
583  	 * you should either allocate it statically, or dynamically at
584  	 * initialization time.
585  	 */
586  		void (*emergency_cleanup)(void);
587  	
588  	/**
589  	 * pNFS functions
590  	 */
591  	
592  	/**
593  	 * @brief Get information about a pNFS device
594  	 *
595  	 * When this function is called, the FSAL should write device
596  	 * information to the @c da_addr_body stream.
597  	 *
598  	 * @param[in]  fsal_hdl     FSAL module
599  	 * @param[out] da_addr_body An XDR stream to which the FSAL is to
600  	 *                          write the layout type-specific information
601  	 *                          corresponding to the deviceid.
602  	 * @param[in]  type         The type of layout that specified the
603  	 *                          device
604  	 * @param[in]  deviceid     The device to look up
605  	 *
606  	 * @return Valid error codes in RFC 5661, p. 365.
607  	 */
608  		 nfsstat4(*getdeviceinfo)(struct fsal_module *fsal_hdl,
609  					  XDR * da_addr_body,
610  					  const layouttype4 type,
611  					  const struct pnfs_deviceid *deviceid);
612  	
613  	/**
614  	 * @brief Max Size of the buffer needed for da_addr_body in getdeviceinfo
615  	 *
616  	 * This function sets policy for XDR buffer allocation in getdeviceinfo.
617  	 * If FSAL has a const size, just return it here. If it is dependent on
618  	 * what the client can take return ~0UL. In any case the buffer allocated will
619  	 * not be bigger than client's requested maximum.
620  	 *
621  	 * @param[in] exp_hdl Filesystem to interrogate
622  	 *
623  	 * @return Max size of the buffer needed for a da_addr_body
624  	 */
625  		 size_t (*fs_da_addr_size)(struct fsal_module *fsal_hdl);
626  	
627  	/**
628  	 * @brief Create a FSAL pNFS data server
629  	 *
630  	 * @param[in]  fsal_hdl		FSAL module
631  	 * @param[in]  parse_node	opaque pointer to parse tree node for
632  	 *				export options to be passed to
633  	 *				load_config_from_node
634  	 * @param[out] handle		FSAL pNFS DS
635  	 *
636  	 * @return FSAL status.
637  	 */
638  		 fsal_status_t (*fsal_pnfs_ds)(struct fsal_module *const fsal_hdl,
639  					       void *parse_node,
640  					       struct fsal_pnfs_ds **const handle);
641  	
642  	/**
643  	 * @brief Initialize FSAL specific values for pNFS data server
644  	 *
645  	 * @param[in]  ops	FSAL pNFS Data Server operations vector
646  	 */
647  		 void (*fsal_pnfs_ds_ops)(struct fsal_pnfs_ds_ops *ops);
648  	
649  	/**
650  	 * @brief Provides function to extract FSAL stats
651  	 *
652  	 * @param[in] fsal_hdl		FSAL module
653  	 * @param[in] iter		opaque pointer to DBusMessageIter
654  	 */
655  		void (*fsal_extract_stats)(struct fsal_module *const fsal_hdl,
656  					   void *iter);
657  	
658  	/**
659  	 * @brief FSAL function to reset FSAL stats
660  	 *
661  	 * @param[in] fsal_hdl          FSAL module
662  	 */
663  		void (*fsal_reset_stats)(struct fsal_module *const fsal_hdl);
664  	
665  	/**@}*/
666  	};
667  	
668  	/**
669  	 * @brief Export operations
670  	 */
671  	
672  	struct export_ops {
673  	/**@{*/
674  	
675  	/**
676  	* Export information
677  	*/
678  	
679  	/**
680  	 * @brief Get the name of the FSAL provisioning the export
681  	 *
682  	 * This function is used to find the name of the ultimate FSAL providing the
683  	 * filesystem.  If FSALs are stacked, then the super-FSAL may want to pass this
684  	 * through to the sub-FSAL to get the name, or add the sub-FSAL's name onto it's
685  	 * own name.
686  	 *
687  	 * @param[in] exp_hdl The export to query.
688  	 * @return Name of FSAL provisioning export
689  	 */
690  		 const char *(*get_name)(struct fsal_export *exp_hdl);
691  	/**@}*/
692  	
693  	/**@{*/
694  	
695  	/**
696  	* Export lifecycle management.
697  	*/
698  	
699  	/**
700  	 * @brief Prepare an export to be unexported
701  	 *
702  	 * This function is called prior to unexporting an export. It should do any
703  	 * preparation that the export requires prior to being removed.
704  	 */
705  		 void (*prepare_unexport)(struct fsal_export *exp_hdl);
706  	
707  	/**
708  	 * @brief Clean up an export when it's unexported
709  	 *
710  	 * This function is called when the export is unexported.  It should release any
711  	 * working data that is not necessary when unexported, but not free the export
712  	 * itself, as there are still references to it.
713  	 *
714  	 * @param[in] exp_hdl	The export to unexport.
715  	 * @param[in] root_obj	The root object of the export
716  	 */
717  		 void (*unexport)(struct fsal_export *exp_hdl,
718  				  struct fsal_obj_handle *root_obj);
719  	
720  	/**
721  	 * @brief Finalize an export
722  	 *
723  	 * This function is called as part of cleanup when the last reference to
724  	 * an export is released and it is no longer part of the list.  It
725  	 * should clean up all private resources and destroy the object.
726  	 *
727  	 * @param[in] exp_hdl The export to release.
728  	 */
729  		 void (*release)(struct fsal_export *exp_hdl);
730  	/**@}*/
731  	
732  	/**@{*/
733  	/**
734  	 * Create an object handles within this export
735  	 */
736  	
737  	/**
738  	 * @brief Look up a path
739  	 *
740  	 * This function looks up a path within the export, it is typically
741  	 * used to get a handle for the root directory of the export.
742  	 *
743  	 * The caller will set the request_mask in attrs_out to indicate the attributes
744  	 * of interest. ATTR_ACL SHOULD NOT be requested and need not be provided. If
745  	 * not all the requested attributes can be provided, this method MUST return
746  	 * an error unless the ATTR_RDATTR_ERR bit was set in the request_mask.
747  	 *
748  	 * Since this method instantiates a new fsal_obj_handle, it will be forced
749  	 * to fetch at least some attributes in order to even know what the object
750  	 * type is (as well as it's fileid and fsid). For this reason, the operation
751  	 * as a whole can be expected to fail if the attributes were not able to be
752  	 * fetched.
753  	 *
754  	 * @param[in]     exp_hdl   The export in which to look up
755  	 * @param[in]     path      The path to look up
756  	 * @param[out]    handle    The object found
757  	 * @param[in,out] attrs_out Optional attributes for newly created object
758  	 *
759  	 * @note On success, @a handle has been ref'd
760  	 *
761  	 * @return FSAL status.
762  	 */
763  		 fsal_status_t (*lookup_path)(struct fsal_export *exp_hdl,
764  					      const char *path,
765  					      struct fsal_obj_handle **handle,
766  					      struct attrlist *attrs_out);
767  	
768  	/**
769  	 * @brief Look up a junction
770  	 *
771  	 * This function returns a handle for the directory behind a junction
772  	 * object.
773  	 *
774  	 * @deprecated This function is not implemented by any FSAL nor is it
775  	 * called.  It exists here as a placeholder for implementation in 2.1
776  	 * as part of the PseudoFSAL work.  Its argument structure will almost
777  	 * certainly change.
778  	 *
779  	 * @param[in]  exp_hdl  Export in which to look up
780  	 * @param[in]  junction The junction object
781  	 * @param[out] handle   The underlying directory handle
782  	 *
783  	 * @return FSAL status.
784  	 */
785  		 fsal_status_t (*lookup_junction)(struct fsal_export *exp_hdl,
786  						  struct fsal_obj_handle *junction,
787  						  struct fsal_obj_handle **handle);
788  	/**
789  	 * @brief Convert a wire handle to a host handle
790  	 *
791  	 * This function extracts a host handle from a wire handle.  That
792  	 * is, when given a handle as passed to a client, this method will
793  	 * extract the handle to create objects.
794  	 *
795  	 * @param[in]     exp_hdl Export handle
796  	 * @param[in]     in_type Protocol through which buffer was received.
797  	 * @param[in]     flags   Flags to describe the wire handle. Example, if
798  	 *			  the handle is a big endian handle.
799  	 * @param[in,out] fh_desc Buffer descriptor.  The address of the
800  	 *                        buffer is given in @c fh_desc->buf and must
801  	 *                        not be changed.  @c fh_desc->len is the
802  	 *                        length of the data contained in the buffer,
803  	 *                        @c fh_desc->len must be updated to the correct
804  	 *                        host handle size.
805  	 *
806  	 * @return FSAL type.
807  	 */
808  		 fsal_status_t (*wire_to_host)(struct fsal_export *exp_hdl,
809  						 fsal_digesttype_t in_type,
810  						 struct gsh_buffdesc *fh_desc,
811  						 int flags);
812  	
813  	/**
814  	 * @brief extract "key" from a host handle
815  	 *
816  	 * This function extracts a "key" from a host handle.  That is, when
817  	 * given a handle that is extracted from wire_to_host() above, this
818  	 * method will extract the unique bits used to index the inode cache.
819  	 *
820  	 * @param[in]     exp_hdl Export handle
821  	 * @param[in,out] fh_desc Buffer descriptor.  The address of the
822  	 *                        buffer is given in @c fh_desc->buf and must
823  	 *                        not be changed.  @c fh_desc->len is the length
824  	 *                        of the data contained in the buffer, @c
825  	 *                        fh_desc->len must be updated to the correct
826  	 *                        size. In other words, the key has to be placed
827  	 *                        at the beginning of the buffer!
828  	 */
829  		 fsal_status_t (*host_to_key)(struct fsal_export *exp_hdl,
830  					      struct gsh_buffdesc *fh_desc);
831  	
832  	/**
833  	 * @brief Create a FSAL object handle from a host handle
834  	 *
835  	 * This function creates a FSAL object handle from a host handle
836  	 * (when an object is no longer in cache but the client still remembers
837  	 * the handle).
838  	 *
839  	 * The caller will set the request_mask in attrs_out to indicate the attributes
840  	 * of interest. ATTR_ACL SHOULD NOT be requested and need not be provided. If
841  	 * not all the requested attributes can be provided, this method MUST return
842  	 * an error unless the ATTR_RDATTR_ERR bit was set in the request_mask.
843  	 *
844  	 * Since this method instantiates a new fsal_obj_handle, it will be forced
845  	 * to fetch at least some attributes in order to even know what the object
846  	 * type is (as well as it's fileid and fsid). For this reason, the operation
847  	 * as a whole can be expected to fail if the attributes were not able to be
848  	 * fetched.
849  	 *
850  	 * @param[in]     exp_hdl   The export in which to create the handle
851  	 * @param[in]     hdl_desc  Buffer descriptor for the host handle
852  	 * @param[out]    handle    FSAL object handle
853  	 * @param[in,out] attrs_out Optional attributes for newly created object
854  	 *
855  	 * @note On success, @a handle has been ref'd
856  	 *
857  	 * @return FSAL status.
858  	 */
859  		 fsal_status_t (*create_handle)(struct fsal_export *exp_hdl,
860  						struct gsh_buffdesc *fh_desc,
861  						struct fsal_obj_handle **handle,
862  						struct attrlist *attrs_out);
863  	/**@}*/
864  	
865  	/**@{*/
866  	/**
867  	 * Statistics and configuration for this filesystem
868  	 */
869  	
870  	/**
871  	 * @brief Get filesystem statistics
872  	 *
873  	 * This function gets information on inodes and space in use and free
874  	 * for a filesystem.  See @c fsal_dynamicinfo_t for details of what to
875  	 * fill out.
876  	 *
877  	 * @param[in]  exp_hdl Export handle to interrogate
878  	 * @param[in]  obj_hdl Directory
879  	 * @param[out] info    Buffer to fill with information
880  	 *
881  	 * @retval FSAL status.
882  	 */
883  		 fsal_status_t (*get_fs_dynamic_info)(struct fsal_export *exp_hdl,
884  						      struct fsal_obj_handle *obj_hdl,
885  						      fsal_dynamicfsinfo_t *info);
886  	/**
887  	 * @brief Export feature test
888  	 *
889  	 * This function checks whether a feature is supported on this
890  	 * filesystem.  The features that can be interrogated are given in the
891  	 * @c fsal_fsinfo_options_t enumeration.
892  	 *
893  	 * @param[in] exp_hdl The export to interrogate
894  	 * @param[in] option  The feature to query
895  	 *
896  	 * @retval true if the feature is supported.
897  	 * @retval false if the feature is unsupported or unknown.
898  	 */
899  		 bool (*fs_supports)(struct fsal_export *exp_hdl,
900  				     fsal_fsinfo_options_t option);
901  	/**
902  	 * @brief Get the greatest file size supported
903  	 *
904  	 * @param[in] exp_hdl Filesystem to interrogate
905  	 *
906  	 * @return Greatest file size supported.
907  	 */
908  		 uint64_t (*fs_maxfilesize)(struct fsal_export *exp_hdl);
909  	
910  	/**
911  	 * @brief Get the greatest read size supported
912  	 *
913  	 * @param[in] exp_hdl Filesystem to interrogate
914  	 *
915  	 * @return Greatest read size supported.
916  	 */
917  		 uint32_t (*fs_maxread)(struct fsal_export *exp_hdl);
918  	
919  	/**
920  	 * @brief Get the greatest write size supported
921  	 *
922  	 * @param[in] exp_hdl Filesystem to interrogate
923  	 *
924  	 * @return Greatest write size supported.
925  	 */
926  		 uint32_t (*fs_maxwrite)(struct fsal_export *exp_hdl);
927  	
928  	/**
929  	 * @brief Get the greatest link count supported
930  	 *
931  	 * @param[in] exp_hdl Filesystem to interrogate
932  	 *
933  	 * @return Greatest link count supported.
934  	 */
935  		 uint32_t (*fs_maxlink)(struct fsal_export *exp_hdl);
936  	
937  	/**
938  	 * @brief Get the greatest name length supported
939  	 *
940  	 * @param[in] exp_hdl Filesystem to interrogate
941  	 *
942  	 * @return Greatest name length supported.
943  	 */
944  		 uint32_t (*fs_maxnamelen)(struct fsal_export *exp_hdl);
945  	
946  	/**
947  	 * @brief Get the greatest path length supported
948  	 *
949  	 * @param[in] exp_hdl Filesystem to interrogate
950  	 *
951  	 * @return Greatest path length supported.
952  	 */
953  		 uint32_t (*fs_maxpathlen)(struct fsal_export *exp_hdl);
954  	
955  	/**
956  	 * @brief Get supported ACL types
957  	 *
958  	 * This function returns a bitmask indicating whether it supports
959  	 * ALLOW, DENY, neither, or both types of ACL.
960  	 *
961  	 * @note Could someone with more ACL support tell me if this is sane?
962  	 * Is it legitimate for an FSAL supporting ACLs to support just ALLOW
963  	 * or just DENY without supporting the other?  It seems fishy to
964  	 * me. -- ACE
965  	 *
966  	 * @param[in] exp_hdl Filesystem to interrogate
967  	 *
968  	 * @return supported ACL types.
969  	 */
970  		 fsal_aclsupp_t (*fs_acl_support)(struct fsal_export *exp_hdl);
971  	
972  	/**
973  	 * @brief Get supported attributes
974  	 *
975  	 * This function returns a list of all attributes that this FSAL will
976  	 * support.  Be aware that this is specifically the attributes in
977  	 * struct attrlist, other NFS attributes (fileid and so forth) are
978  	 * supported through other means.
979  	 *
980  	 * @param[in] exp_hdl Filesystem to interrogate
981  	 *
982  	 * @return supported attributes.
983  	 */
984  		 attrmask_t (*fs_supported_attrs)(struct fsal_export *exp_hdl);
985  	
986  	/**
987  	 * @brief Get umask applied to created files
988  	 *
989  	 * @note This seems fishy to me.  Is this actually supported properly?
990  	 * And is it something we want the FSAL being involved in?  We already
991  	 * have the functions in Protocol/NFS specifying a default mode. -- ACE
992  	 *
993  	 * @param[in] exp_hdl Filesystem to interrogate
994  	 *
995  	 * @return creation umask.
996  	 */
997  		 uint32_t (*fs_umask)(struct fsal_export *exp_hdl);
998  	/**@}*/
999  	
1000 	/**@{*/
1001 	
1002 	/**
1003 	 * Quotas are managed at the file system (export) level.  Someone who
1004 	 * uses quotas, please look over these comments to check/expand them.
1005 	 */
1006 	
1007 	/**
1008 	 * @brief Check if quotas allow an operation
1009 	 *
1010 	 * This function checks to see if a user has overrun a quota and
1011 	 * should be disallowed from performing an operation that would
1012 	 * consume blocks or inodes.
1013 	 *
1014 	 * @param[in] exp_hdl    The export to interrogate
1015 	 * @param[in] filepath   The path within the export to check
1016 	 * @param[in] quota_type Whether we are checking inodes or blocks
1017 	 *
1018 	 * @return FSAL types.
1019 	 */
1020 		 fsal_status_t (*check_quota)(struct fsal_export *exp_hdl,
1021 					      const char *filepath, int quota_type);
1022 	
1023 	/**
1024 	 * @brief Get a user's quota
1025 	 *
1026 	 * This function retrieves a given user's quota.
1027 	 *
1028 	 * @param[in]  exp_hdl    The export to interrogate
1029 	 * @param[in]  filepath   The path within the export to check
1030 	 * @param[in]  quota_type Whether we are checking inodes or blocks
1031 	 * @param[in]  quota_id   Id for which quota is set
1032 	 * @param[out] quota      The user's quota
1033 	 *
1034 	 * @return FSAL types.
1035 	 */
1036 		 fsal_status_t (*get_quota)(struct fsal_export *exp_hdl,
1037 					    const char *filepath, int quota_type,
1038 					    int quota_id,
1039 					    fsal_quota_t *quota);
1040 	
1041 	/**
1042 	 * @brief Set a user's quota
1043 	 *
1044 	 * This function sets a user's quota.
1045 	 *
1046 	 * @param[in]  exp_hdl    The export to interrogate
1047 	 * @param[in]  filepath   The path within the export to check
1048 	 * @param[in]  quota_type Whether we are checking inodes or blocks
1049 	 * @param[in]  quota_id   Id for which quota is set
1050 	 * @param[in]  quota      The values to set for the quota
1051 	 * @param[out] resquota   New values set (optional)
1052 	 *
1053 	 * @return FSAL types.
1054 	 */
1055 		 fsal_status_t (*set_quota)(struct fsal_export *exp_hdl,
1056 					    const char *filepath, int quota_type,
1057 					    int quota_id,
1058 					    fsal_quota_t *quota,
1059 					    fsal_quota_t *resquota);
1060 	/**@}*/
1061 	
1062 	/**@{*/
1063 	/**
1064 	 * pNFS functions
1065 	 */
1066 	
1067 	/**
1068 	 * @brief Get list of available devices
1069 	 *
1070 	 * This function should populate calls @c cb @c values representing the
1071 	 * low quad of deviceids it wishes to make the available to the
1072 	 * caller.  it should continue calling @c cb until @c cb returns false
1073 	 * or it runs out of deviceids to make available.  If @c cb returns
1074 	 * false, it should assume that @c cb has not stored the most recent
1075 	 * deviceid and set @c res->cookie to a value that will begin witht he
1076 	 * most recently provided.
1077 	 *
1078 	 * If it wishes to return no deviceids, it may set @c res->eof to true
1079 	 * without calling @c cb at all.
1080 	 *
1081 	 * @param[in]     exp_hdl Export handle
1082 	 * @param[in]     type    Type of layout to get devices for
1083 	 * @param[in]     cb      Function taking device ID halves
1084 	 * @param[in,out] res     In/out and output arguments of the function
1085 	 *
1086 	 * @return Valid error codes in RFC 5661, pp. 365-6.
1087 	 */
1088 		 nfsstat4(*getdevicelist)(struct fsal_export *exp_hdl,
1089 					  layouttype4 type, void *opaque,
1090 					  bool (*cb)(void *opaque, const uint64_t id),
1091 					  struct fsal_getdevicelist_res *res);
1092 	
1093 	/**
1094 	 * @brief Get layout types supported by export
1095 	 *
1096 	 * This function is the handler of the NFS4.1 FATTR4_FS_LAYOUT_TYPES file
1097 	 * attribute. (See RFC)
1098 	 *
1099 	 * @param[in]  exp_hdl Filesystem to interrogate
1100 	 * @param[out] count   Number of layout types in array
1101 	 * @param[out] types   Static array of layout types that must not be
1102 	 *                     freed or modified and must not be dereferenced
1103 	 *                     after export reference is relinquished
1104 	 */
1105 		void (*fs_layouttypes)(struct fsal_export *exp_hdl, int32_t *count,
1106 				       const layouttype4 **types);
1107 	
1108 	/**
1109 	 * @brief Get layout block size for export
1110 	 *
1111 	 * This function is the handler of the NFS4.1 FATTR4_LAYOUT_BLKSIZE f-attribute.
1112 	 *
1113 	 * This is the preferred read/write block size.  Clients are requested
1114 	 * (but don't have to) read and write in multiples.
1115 	 *
1116 	 * NOTE: The linux client only asks for this in blocks-layout, where this is the
1117 	 * filesystem wide block-size. (Minimum write size and alignment)
1118 	 *
1119 	 * @param[in] exp_hdl Filesystem to interrogate
1120 	 *
1121 	 * @return The preferred layout block size.
1122 	 */
1123 		 uint32_t (*fs_layout_blocksize)(struct fsal_export *exp_hdl);
1124 	
1125 	/**
1126 	 * @brief Maximum number of segments we will use
1127 	 *
1128 	 * This function returns the maximum number of segments that will be
1129 	 * used to construct the response to any single layoutget call.  Bear
1130 	 * in mind that current clients only support 1 segment.
1131 	 *
1132 	 * @param[in] exp_hdl Filesystem to interrogate
1133 	 *
1134 	 * @return The Maximum number of layout segments in a campound layoutget.
1135 	 */
1136 		 uint32_t (*fs_maximum_segments)(struct fsal_export *exp_hdl);
1137 	
1138 	/**
1139 	 * @brief Size of the buffer needed for loc_body at layoutget
1140 	 *
1141 	 * This function sets policy for XDR buffer allocation in layoutget vector
1142 	 * below. If FSAL has a const size, just return it here. If it is dependent on
1143 	 * what the client can take return ~0UL. In any case the buffer allocated will
1144 	 * not be bigger than client's requested maximum.
1145 	 *
1146 	 * @param[in] exp_hdl Filesystem to interrogate
1147 	 *
1148 	 * @return Max size of the buffer needed for a loc_body
1149 	 */
1150 		 size_t (*fs_loc_body_size)(struct fsal_export *exp_hdl);
1151 	
1152 	/**
1153 	 * @brief Get write verifier
1154 	 *
1155 	 * This function is called by write and commit to match the commit verifier
1156 	 * with the one returned on  write.
1157 	 *
1158 	 * @param[in] exp_hdl	Export to query
1159 	 * @param[in,out] verf_desc Address and length of verifier
1160 	 */
1161 		void (*get_write_verifier)(struct fsal_export *exp_hdl,
1162 					   struct gsh_buffdesc *verf_desc);
1163 	
1164 	/**@}*/
1165 	
1166 	/**
1167 	 * @brief Allocate a state_t structure
1168 	 *
1169 	 * Note that this is not expected to fail since memory allocation is
1170 	 * expected to abort on failure.
1171 	 *
1172 	 * @param[in] exp_hdl               Export state_t will be associated with
1173 	 * @param[in] state_type            Type of state to allocate
1174 	 * @param[in] related_state         Related state if appropriate
1175 	 *
1176 	 * @returns a state structure.
1177 	 */
1178 	
1179 		struct state_t *(*alloc_state)(struct fsal_export *exp_hdl,
1180 					       enum state_type state_type,
1181 					       struct state_t *related_state);
1182 	
1183 	/**
1184 	 * @brief Free a state_t structure
1185 	 *
1186 	 * @param[in] exp_hdl               Export state_t is associated with
1187 	 * @param[in] state                 state_t structure to free.
1188 	 *
1189 	 * @returns NULL on failure otherwise a state structure.
1190 	 */
1191 	
1192 		void (*free_state)(struct fsal_export *exp_hdl, struct state_t *state);
1193 	
1194 	/**
1195 	 * @brief Check to see if a user is superuser
1196 	 *
1197 	 * @param[in] exp_hdl               Export state_t is associated with
1198 	 * @param[in] creds                 Credentials to check for superuser
1199 	 *
1200 	 * @returns NULL on failure otherwise a state structure.
1201 	 */
1202 	
1203 		bool (*is_superuser)(struct fsal_export *exp_hdl,
1204 				     const struct user_cred *creds);
1205 	
1206 	/**
1207 	 * @brief Get the expiration time for parent handle.
1208 	 *
1209 	 * @param[in] exp_hdl Filesystem to interrogate
1210 	 *
1211 	 * @return Expiration time for parent handle
1212 	 */
1213 	
1214 		int32_t (*fs_expiretimeparent)(struct fsal_export *exp_hdl);
1215 	};
1216 	
1217 	/**
1218 	 * @brief Filesystem operations
1219 	 */
1220 	
1221 	typedef void (*fsal_async_cb)(struct fsal_obj_handle *obj, fsal_status_t ret,
1222 				      void *obj_data, void *caller_data);
1223 	
1224 	typedef int (*claim_filesystem_cb)(struct fsal_filesystem *fs,
1225 					   struct fsal_export *exp);
1226 	
1227 	typedef void (*unclaim_filesystem_cb)(struct fsal_filesystem *fs);
1228 	
1229 	enum fsid_type {
1230 		FSID_NO_TYPE,
1231 		FSID_ONE_UINT64,
1232 		FSID_MAJOR_64,
1233 		FSID_TWO_UINT64,
1234 		FSID_TWO_UINT32,
1235 		FSID_DEVICE
1236 	};
1237 	
1238 	static inline uint64_t squash_fsid(const struct fsal_fsid__ *fsid)
1239 	{
1240 		return fsid->major ^ (fsid->minor << 32 | fsid->minor >> 32);
1241 	}
1242 	
1243 	static inline int sizeof_fsid(enum fsid_type type)
1244 	{
1245 		switch (type) {
1246 		case FSID_NO_TYPE:
1247 			return 0;
1248 		case FSID_ONE_UINT64:
1249 		case FSID_MAJOR_64:
1250 			return sizeof(uint64_t);
1251 		case FSID_TWO_UINT64:
1252 			return 2 * sizeof(uint64_t);
1253 		case FSID_TWO_UINT32:
1254 		case FSID_DEVICE:
1255 			return 2 * sizeof(uint32_t);
1256 		}
1257 	
1258 		return -1;
1259 	}
1260 	
1261 	/**
1262 	 * @brief Directory cookie
1263 	 */
1264 	
1265 	typedef uint64_t fsal_cookie_t;
1266 	
1267 	/* Cookie values 0, 1, and 2 are reserved by NFS:
1268 	 * 0 is "start from beginning"
1269 	 * 1 is the cookie associated with the "." entry
1270 	 * 2 is the cookie associated with the ".." entry
1271 	 *
1272 	 * FSALs that support compute_readdir_cookie that are for some reason unable
1273 	 * to compute the cookie for the very first entry (other than . and ..)
1274 	 * should return FIRST_COOKIE. Caching layers such as MDCACHE should treat an
1275 	 * insert of an entry with cookie 3 as inserting a new first entry, and then
1276 	 * compute a new cookie for the old first entry - they can safely assume the
1277 	 * sort order doesn't change which may allow for optimization of things like'
1278 	 * AVL trees.
1279 	 */
1280 	#define FIRST_COOKIE 3
1281 	
1282 	enum fsal_dir_result {
1283 		/** Continue readdir, call back with another dirent. */
1284 		DIR_CONTINUE,
1285 		/** Continue supplying entries if readahead is supported, otherwise
1286 		 *  stop providing entries.
1287 		 */
1288 		DIR_READAHEAD,
1289 		/** Terminate readdir. */
1290 		DIR_TERMINATE,
1291 	};
1292 	
1293 	const char *fsal_dir_result_str(enum fsal_dir_result result);
1294 	
1295 	/**
1296 	 * @brief Callback to provide readdir caller with each directory entry
1297 	 *
1298 	 * The called function will indicate if readdir should continue, terminate,
1299 	 * terminate and mark cookie, or continue and mark cookie. In the last case,
1300 	 * the called function may also return a cookie if requested in the ret_cookie
1301 	 * parameter (which may be NULL if the caller doesn't need to mark cookies).
1302 	 * If ret_cookie is 0, the caller had no cookie to return.
1303 	 *
1304 	 * @param[in]      name         The name of the entry
1305 	 * @param[in]      obj          The fsal_obj_handle describing the entry
1306 	 * @param[in]      attrs        The requested attribues for the entry (see
1307 	 *                              readdir attrmask parameter)
1308 	 * @param[in]      dir_state    Opaque pointer to be passed to callback
1309 	 * @param[in]      cookie       An FSAL generated cookie for the entry
1310 	 *
1311 	 * @returns fsal_dir_result above
1312 	 */
1313 	typedef enum fsal_dir_result (*fsal_readdir_cb)(
1314 					const char *name, struct fsal_obj_handle *obj,
1315 					struct attrlist *attrs,
1316 					void *dir_state, fsal_cookie_t cookie);
1317 	
1318 	/**
1319 	 * @brief Argument for read2/write2 and their callbacks
1320 	 *
1321 	 */
1322 	struct fsal_io_arg {
1323 		size_t io_amount;	/**< Total amount of I/O actually done */
1324 		struct io_info *info;	/**< More info about data for read_plus */
1325 		union {
1326 			bool end_of_file;	/**< True if end-of-file reached */
1327 			bool fsal_stable;	/**< requested/achieved stability */
1328 		};
1329 		struct state_t *state;	/**< State to use for read (or NULL) */
1330 		uint64_t offset;	/**< Offset into file to read */
1331 		int iov_count;		/**< Number of vectors in iov */
1332 		struct iovec iov[];	/**< Vector of buffers to fill */
1333 	};
1334 	
1335 	/**
1336 	 * @brief FSAL object operations vector
1337 	 */
1338 	
1339 	struct fsal_obj_ops {
1340 	/**@{*/
1341 	
1342 	/**
1343 	 * Lifecycle management
1344 	 */
1345 	
1346 	/**
1347 	 * @brief Get a reference to a handle
1348 	 *
1349 	 * Refcounting is required for all FSALs. An FSAL that will have FSAL_MDCACHE
1350 	 * stacked on top need not handle this as FSAL_MDCACHE will handle it.
1351 	 *
1352 	 * @param[in] obj_hdl Handle to release
1353 	 */
1354 		 void (*get_ref)(struct fsal_obj_handle *obj_hdl);
1355 	
1356 	/**
1357 	 * @brief Put a reference to a handle
1358 	 *
1359 	 * Refcounting is required for all FSALs. An FSAL that will have FSAL_MDCACHE
1360 	 * stacked on top need not handle this as FSAL_MDCACHE will handle it.
1361 	 *
1362 	 * @param[in] obj_hdl Handle to release
1363 	 */
1364 		 void (*put_ref)(struct fsal_obj_handle *obj_hdl);
1365 	
1366 	/**
1367 	 * @brief Clean up a filehandle
1368 	 *
1369 	 * This function cleans up private resources associated with a
1370 	 * filehandle and deallocates it.  Implement this method or you will
1371 	 * leak.  Refcount (if used) should be 1
1372 	 *
1373 	 * @param[in] obj_hdl Handle to release
1374 	 */
1375 		 void (*release)(struct fsal_obj_handle *obj_hdl);
1376 	
1377 	/**
1378 	 * @brief Merge a duplicate handle with an original handle
1379 	 *
1380 	 * This function is used if an upper layer detects that a duplicate
1381 	 * object handle has been created. It allows the FSAL to merge anything
1382 	 * from the duplicate back into the original.
1383 	 *
1384 	 * The caller must release the object (the caller may have to close
1385 	 * files if the merge is unsuccessful).
1386 	 *
1387 	 * @param[in]  orig_hdl  Original handle
1388 	 * @param[in]  dupe_hdl Handle to merge into original
1389 	 *
1390 	 * @return FSAL status.
1391 	 *
1392 	 */
1393 		 fsal_status_t (*merge)(struct fsal_obj_handle *orig_hdl,
1394 					struct fsal_obj_handle *dupe_hdl);
1395 	
1396 	/**@}*/
1397 	
1398 	/**@{*/
1399 	
1400 	/**
1401 	 * Directory operations
1402 	 */
1403 	
1404 	/**
1405 	 * @brief Look up a filename
1406 	 *
1407 	 * This function looks up the given name in the supplied directory.
1408 	 *
1409 	 * @note The old version of the FSAL had a special case for this
1410 	 * function, such that if the directory handle and path were both
1411 	 * NULL, a handle to the root of the export was returned.  This
1412 	 * special case is no longer supported and should not be implemented.
1413 	 *
1414 	 * The caller will set the request_mask in attrs_out to indicate the attributes
1415 	 * of interest. ATTR_ACL SHOULD NOT be requested and need not be provided. If
1416 	 * not all the requested attributes can be provided, this method MUST return
1417 	 * an error unless the ATTR_RDATTR_ERR bit was set in the request_mask.
1418 	 *
1419 	 * Since this method instantiates a new fsal_obj_handle, it will be forced
1420 	 * to fetch at least some attributes in order to even know what the object
1421 	 * type is (as well as it's fileid and fsid). For this reason, the operation
1422 	 * as a whole can be expected to fail if the attributes were not able to be
1423 	 * fetched.
1424 	 *
1425 	 * @param[in]     dir_hdl   Directory to search
1426 	 * @param[in]     path      Name to look up
1427 	 * @param[out]    handle    Object found
1428 	 * @param[in,out] attrs_out Optional attributes for newly created object
1429 	 *
1430 	 * @note On success, @a handle has been ref'd
1431 	 *
1432 	 * @return FSAL status.
1433 	 */
1434 		 fsal_status_t (*lookup)(struct fsal_obj_handle *dir_hdl,
1435 					 const char *path,
1436 					 struct fsal_obj_handle **handle,
1437 					 struct attrlist *attrs_out);
1438 	
1439 	/**
1440 	 * @brief Read a directory
1441 	 *
1442 	 * This function reads directory entries from the FSAL and supplies
1443 	 * them to a callback.
1444 	 *
1445 	 * @param[in]  dir_hdl   Directory to read
1446 	 * @param[in]  whence    Point at which to start reading.  NULL to
1447 	 *                       start at beginning.
1448 	 * @param[in]  dir_state Opaque pointer to be passed to callback
1449 	 * @param[in]  cb        Callback to receive names
1450 	 * @param[in]  attrmask  Indicate which attributes the caller is interested in
1451 	 * @param[out] eof       true if the last entry was reached
1452 	 *
1453 	 * @return FSAL status.
1454 	 */
1455 		 fsal_status_t (*readdir)(struct fsal_obj_handle *dir_hdl,
1456 					  fsal_cookie_t *whence,
1457 					  void *dir_state,
1458 					  fsal_readdir_cb cb,
1459 					  attrmask_t attrmask,
1460 					  bool *eof);
1461 	
1462 	/**
1463 	 * @brief Compute the readdir cookie for a given filename.
1464 	 *
1465 	 * Some FSALs are able to compute the cookie for a filename deterministically
1466 	 * from the filename. They also have a defined order of entries in a directory
1467 	 * based on the name (could be strcmp sort, could be strict alpha sort, could
1468 	 * be deterministic order based on cookie - in any case, the dirent_cmp method
1469 	 * will also be provided.
1470 	 *
1471 	 * The returned cookie is the cookie that can be passed as whence to FIND that
1472 	 * directory entry. This is different than the cookie passed in the readdir
1473 	 * callback (which is the cookie of the NEXT entry).
1474 	 *
1475 	 * @param[in]  parent  Directory file name belongs to.
1476 	 * @param[in]  name    File name to produce the cookie for.
1477 	 *
1478 	 * @retval 0 if not supported.
1479 	 * @returns The cookie value.
1480 	 */
1481 		fsal_cookie_t (*compute_readdir_cookie)(struct fsal_obj_handle *parent,
1482 							const char *name);
1483 	
1484 	/**
1485 	 * @brief Help sort dirents.
1486 	 *
1487 	 * For FSALs that are able to compute the cookie for a filename
1488 	 * deterministically from the filename, there must also be a defined order of
1489 	 * entries in a directory based on the name (could be strcmp sort, could be
1490 	 * strict alpha sort, could be deterministic order based on cookie).
1491 	 *
1492 	 * Although the cookies could be computed, the caller will already have them
1493 	 * and thus will provide them to save compute time.
1494 	 *
1495 	 * @param[in]  parent   Directory entries belong to.
1496 	 * @param[in]  name1    File name of first dirent
1497 	 * @param[in]  cookie1  Cookie of first dirent
1498 	 * @param[in]  name2    File name of second dirent
1499 	 * @param[in]  cookie2  Cookie of second dirent
1500 	 *
1501 	 * @retval < 0 if name1 sorts before name2
1502 	 * @retval == 0 if name1 sorts the same as name2
1503 	 * @retval >0 if name1 sorts after name2
1504 	 */
1505 		int (*dirent_cmp)(struct fsal_obj_handle *parent,
1506 				  const char *name1, fsal_cookie_t cookie1,
1507 				  const char *name2, fsal_cookie_t cookie2);
1508 	/**@}*/
1509 	
1510 	/**@{*/
1511 	
1512 	/**
1513 	 * Creation operations
1514 	 */
1515 	
1516 	/**
1517 	 * @brief Create a directory
1518 	 *
1519 	 * This function creates a new directory.
1520 	 *
1521 	 * For support_ex, this method will handle attribute setting. The caller
1522 	 * MUST include the mode attribute and SHOULD NOT include the owner or
1523 	 * group attributes if they are the same as the op_ctx->cred.
1524 	 *
1525 	 * The caller is expected to invoke fsal_release_attrs to release any
1526 	 * resources held by the set attributes. The FSAL layer MAY have added an
1527 	 * inherited ACL.
1528 	 *
1529 	 * The caller will set the request_mask in attrs_out to indicate the attributes
1530 	 * of interest. ATTR_ACL SHOULD NOT be requested and need not be provided. If
1531 	 * not all the requested attributes can be provided, this method MUST return
1532 	 * an error unless the ATTR_RDATTR_ERR bit was set in the request_mask.
1533 	 *
1534 	 * Since this method instantiates a new fsal_obj_handle, it will be forced
1535 	 * to fetch at least some attributes in order to even know what the object
1536 	 * type is (as well as it's fileid and fsid). For this reason, the operation
1537 	 * as a whole can be expected to fail if the attributes were not able to be
1538 	 * fetched.
1539 	 *
1540 	 * @param[in]     dir_hdl   Directory in which to create the directory
1541 	 * @param[in]     name      Name of directory to create
1542 	 * @param[in]     attrs_in  Attributes to set on newly created object
1543 	 * @param[out]    new_obj   Newly created object
1544 	 * @param[in,out] attrs_out Optional attributes for newly created object
1545 	 *
1546 	 * @note On success, @a new_obj has been ref'd
1547 	 *
1548 	 * @return FSAL status.
1549 	 */
1550 		 fsal_status_t (*mkdir)(struct fsal_obj_handle *dir_hdl,
1551 					const char *name, struct attrlist *attrs_in,
1552 					struct fsal_obj_handle **new_obj,
1553 					struct attrlist *attrs_out);
1554 	
1555 	/**
1556 	 * @brief Create a special file
1557 	 *
1558 	 * This function creates a new special file.
1559 	 *
1560 	 * For support_ex, this method will handle attribute setting. The caller
1561 	 * MUST include the mode attribute and SHOULD NOT include the owner or
1562 	 * group attributes if they are the same as the op_ctx->cred.
1563 	 *
1564 	 * If the node type has rawdev info, then @a attrs_in MUST have the rawdev field
1565 	 * set.
1566 	 *
1567 	 * The caller is expected to invoke fsal_release_attrs to release any
1568 	 * resources held by the set attributes. The FSAL layer MAY have added an
1569 	 * inherited ACL.
1570 	 *
1571 	 * The caller will set the request_mask in attrs_out to indicate the attributes
1572 	 * of interest. ATTR_ACL SHOULD NOT be requested and need not be provided. If
1573 	 * not all the requested attributes can be provided, this method MUST return
1574 	 * an error unless the ATTR_RDATTR_ERR bit was set in the request_mask.
1575 	 *
1576 	 * Since this method instantiates a new fsal_obj_handle, it will be forced
1577 	 * to fetch at least some attributes in order to even know what the object
1578 	 * type is (as well as it's fileid and fsid). For this reason, the operation
1579 	 * as a whole can be expected to fail if the attributes were not able to be
1580 	 * fetched.
1581 	 *
1582 	 * @param[in]     dir_hdl   Directory in which to create the object
1583 	 * @param[in]     name      Name of object to create
1584 	 * @param[in]     nodetype  Type of special file to create
1585 	 * @param[in]     attrs_in  Attributes to set on newly created object
1586 	 * @param[out]    new_obj   Newly created object
1587 	 * @param[in,out] attrs_out Optional attributes for newly created object
1588 	 *
1589 	 * @note On success, @a new_obj has been ref'd
1590 	 *
1591 	 * @return FSAL status.
1592 	 */
1593 		 fsal_status_t (*mknode)(struct fsal_obj_handle *dir_hdl,
1594 					 const char *name,
1595 					 object_file_type_t nodetype,
1596 					 struct attrlist *attrs_in,
1597 					 struct fsal_obj_handle **new_obj,
1598 					 struct attrlist *attrs_out);
1599 	
1600 	/**
1601 	 * @brief Create a symbolic link
1602 	 *
1603 	 * This function creates a new symbolic link.
1604 	 *
1605 	 * For support_ex, this method will handle attribute setting. The caller
1606 	 * MUST include the mode attribute and SHOULD NOT include the owner or
1607 	 * group attributes if they are the same as the op_ctx->cred.
1608 	 *
1609 	 * The caller is expected to invoke fsal_release_attrs to release any
1610 	 * resources held by the set attributes. The FSAL layer MAY have added an
1611 	 * inherited ACL.
1612 	 *
1613 	 * The caller will set the request_mask in attrs_out to indicate the attributes
1614 	 * of interest. ATTR_ACL SHOULD NOT be requested and need not be provided. If
1615 	 * not all the requested attributes can be provided, this method MUST return
1616 	 * an error unless the ATTR_RDATTR_ERR bit was set in the request_mask.
1617 	 *
1618 	 * Since this method instantiates a new fsal_obj_handle, it will be forced
1619 	 * to fetch at least some attributes in order to even know what the object
1620 	 * type is (as well as it's fileid and fsid). For this reason, the operation
1621 	 * as a whole can be expected to fail if the attributes were not able to be
1622 	 * fetched.
1623 	 *
1624 	 * @param[in]     dir_hdl   Directory in which to create the object
1625 	 * @param[in]     name      Name of object to create
1626 	 * @param[in]     link_path Content of symbolic link
1627 	 * @param[in]     attrs_in  Attributes to set on newly created object
1628 	 * @param[out]    new_obj   Newly created object
1629 	 * @param[in,out] attrs_out Optional attributes for newly created object
1630 	 *
1631 	 * @note On success, @a new_obj has been ref'd
1632 	 *
1633 	 * @return FSAL status.
1634 	 */
1635 		 fsal_status_t (*symlink)(struct fsal_obj_handle *dir_hdl,
1636 					  const char *name,
1637 					  const char *link_path,
1638 					  struct attrlist *attrs_in,
1639 					  struct fsal_obj_handle **new_obj,
1640 					  struct attrlist *attrs_out);
1641 	/**@}*/
1642 	
1643 	/**@{*/
1644 	
1645 	/**
1646 	 * File object operations
1647 	 */
1648 	
1649 	/**
1650 	 * @brief Read the content of a link
1651 	 *
1652 	 * This function reads the content of a symbolic link.  The FSAL will
1653 	 * allocate a buffer and store its address and the link length in the
1654 	 * link_content gsh_buffdesc.  The caller *must* free this buffer with
1655 	 * gsh_free.
1656 	 *
1657 	 * The symlink content passed back *must* be null terminated and the
1658 	 * length indicated in the buffer description *must* include the
1659 	 * terminator.
1660 	 *
1661 	 * @param[in]  obj_hdl      Link to read
1662 	 * @param[out] link_content Buffdesc to which the FSAL will store
1663 	 *                          the address of the buffer holding the
1664 	 *                          link and the link length.
1665 	 * @param[out] refresh      true if the content are to be retrieved
1666 	 *                          from the underlying filesystem rather
1667 	 *                          than cache
1668 	 *
1669 	 * @return FSAL status.
1670 	 */
1671 		 fsal_status_t (*readlink)(struct fsal_obj_handle *obj_hdl,
1672 					   struct gsh_buffdesc *link_content,
1673 					   bool refresh);
1674 	
1675 	/**
1676 	 * @brief Check access for a given user against a given object
1677 	 *
1678 	 * This function checks whether a given user is allowed to perform the
1679 	 * specified operations against the supplied file.  The goal is to
1680 	 * allow filesystem specific semantics to be applied to cached
1681 	 * metadata.
1682 	 *
1683 	 * This method must read attributes and/or get them from a cache.
1684 	 *
1685 	 * @param[in] obj_hdl     Handle to check
1686 	 * @param[in] access_type Access requested
1687 	 * @param[out] allowed    Returned access that could be granted
1688 	 * @param[out] denied     Returned access that would be granted
1689 	 * @param[in] owner_skip  Skip test if op_ctx->creds is owner
1690 	 *
1691 	 * @return FSAL status.
1692 	 */
1693 		 fsal_status_t (*test_access)(struct fsal_obj_handle *obj_hdl,
1694 					      fsal_accessflags_t access_type,
1695 					      fsal_accessflags_t *allowed,
1696 					      fsal_accessflags_t *denied,
1697 					      bool owner_skip);
1698 	
1699 	/**
1700 	 * @brief Get attributes
1701 	 *
1702 	 * This function fetches the attributes for the object. The attributes
1703 	 * requested in the mask are copied out (though other attributes might
1704 	 * be copied out).
1705 	 *
1706 	 * The caller will set the request_mask in attrs_out to indicate the attributes
1707 	 * of interest. ATTR_ACL SHOULD NOT be requested and need not be provided. If
1708 	 * not all the requested attributes can be provided, this method MUST return
1709 	 * an error unless the ATTR_RDATTR_ERR bit was set in the request_mask.
1710 	 *
1711 	 * The caller MUST call fsal_release_attrs when done with the copied
1712 	 * out attributes. This will release any attributes that might take
1713 	 * additional memory.
1714 	 *
1715 	 * @param[in]  obj_hdl    Object to query
1716 	 * @param[out] attrs_out  Attribute list for file
1717 	 *
1718 	 * @return FSAL status.
1719 	 */
1720 		 fsal_status_t (*getattrs)(struct fsal_obj_handle *obj_hdl,
1721 					   struct attrlist *attrs_out);
1722 	
1723 	/**
1724 	 * @brief Create a new link
1725 	 *
1726 	 * This function creates a new name for an existing object.
1727 	 *
1728 	 * @param[in] obj_hdl     Object to be linked to
1729 	 * @param[in] destdir_hdl Directory in which to create the link
1730 	 * @param[in] name        Name for link
1731 	 *
1732 	 * @return FSAL status
1733 	 */
1734 		 fsal_status_t (*link)(struct fsal_obj_handle *obj_hdl,
1735 				       struct fsal_obj_handle *destdir_hdl,
1736 				       const char *name);
1737 	
1738 	/**
1739 	 * @brief Rename a file
1740 	 *
1741 	 * This function renames a file (technically it changes the name of
1742 	 * one link, which may be the only link to the file.)
1743 	 *
1744 	 * @param[in] olddir_hdl Old parent directory
1745 	 * @param[in] old_name   Old name
1746 	 * @param[in] newdir_hdl New parent directory
1747 	 * @param[in] new_name   New name
1748 	 *
1749 	 * @return FSAL status
1750 	 */
1751 		 fsal_status_t (*rename)(struct fsal_obj_handle *obj_hdl,
1752 					 struct fsal_obj_handle *olddir_hdl,
1753 					 const char *old_name,
1754 					 struct fsal_obj_handle *newdir_hdl,
1755 					 const char *new_name);
1756 	/**
1757 	 * @brief Remove a name from a directory
1758 	 *
1759 	 * This function removes a name from a directory and possibly deletes
1760 	 * the file so named.
1761 	 *
1762 	 * @param[in] dir_hdl The directory from which to remove the name
1763 	 * @param[in] obj_hdl The object being removed
1764 	 * @param[in] name    The name to remove
1765 	 *
1766 	 * @return FSAL status.
1767 	 */
1768 		 fsal_status_t (*unlink)(struct fsal_obj_handle *dir_hdl,
1769 					 struct fsal_obj_handle *obj_hdl,
1770 					 const char *name);
1771 	
1772 	/**@}*/
1773 	
1774 	/**@{*/
1775 	/**
1776 	 * I/O management
1777 	 */
1778 	
1779 	/**
1780 	 * @brief Seek to data or hole
1781 	 *
1782 	 * This function seek to data or hole in a file.
1783 	 *
1784 	 * @param[in]  obj_hdl      File to be written
1785 	 * @param[in,out] info      Information about the data
1786 	 *
1787 	 * @return FSAL status.
1788 	 */
1789 		 fsal_status_t (*seek)(struct fsal_obj_handle *obj_hdl,
1790 				       struct io_info *info);
1791 	/**
1792 	 * @brief IO Advise
1793 	 *
1794 	 * This function give hints to fs.
1795 	 *
1796 	 * @param[in]  obj_hdl      File to be written
1797 	 * @param[in,out] info      Information about the data
1798 	 *
1799 	 * @return FSAL status.
1800 	 */
1801 		 fsal_status_t (*io_advise)(struct fsal_obj_handle *obj_hdl,
1802 					    struct io_hints *hints);
1803 	
1804 	/**
1805 	 * @brief Close a file
1806 	 *
1807 	 * This function closes a file.  It is protected by the Cache inode
1808 	 * content lock.  This should return ERR_FSAL_NOT_OPENED if the global FD for
1809 	 * this obj was not open.
1810 	 *
1811 	 * @param[in] obj_hdl File to close
1812 	 *
1813 	 * @return FSAL status.
1814 	 */
1815 		 fsal_status_t (*close)(struct fsal_obj_handle *obj_hdl);
1816 	
1817 	/**
1818 	 * @brief Reserve/Deallocate space in a region of a file
1819 	 *
1820 	 * @param[in] obj_hdl File to which bytes should be allocated
1821 	 * @param[in] state   open stateid under which to do the allocation
1822 	 * @param[in] offset  offset at which to begin the allocation
1823 	 * @param[in] length  length of the data to be allocated
1824 	 * @param[in] allocate Should space be allocated or deallocated?
1825 	 *
1826 	 * @return FSAL status.
1827 	 */
1828 		 fsal_status_t (*fallocate)(struct fsal_obj_handle *obj_hdl,
1829 					    struct state_t *state, uint64_t offset,
1830 					    uint64_t length, bool allocate);
1831 	/**@}*/
1832 	
1833 	/**@{*/
1834 	
1835 	/**
1836 	 * Extended attribute management
1837 	 */
1838 	
1839 	/**
1840 	 * @brief List extended attributes on a file
1841 	 *
1842 	 * This function gets a list of attributes on a given file.
1843 	 *
1844 	 * @param[in]  obj_hdl        File to interrogate
1845 	 * @param[in]  cookie         Attribute at which to start
1846 	 * @param[out] xattrs_tab     Array to which to write attributes
1847 	 * @param[in]  xattrs_tabsize Size of array
1848 	 * @param[out] nb_returned    Number of entries returned
1849 	 *
1850 	 * @return FSAL status.
1851 	 */
1852 		 fsal_status_t (*list_ext_attrs)(struct fsal_obj_handle *obj_hdl,
1853 						 unsigned int cookie,
1854 						 struct fsal_xattrent *xattrs_tab,
1855 						 unsigned int xattrs_tabsize,
1856 						 unsigned int *nb_returned,
1857 						 int *end_of_list);
1858 	
1859 	/**
1860 	 * @brief Get a number for an attribute name
1861 	 *
1862 	 * This function returns an index for a given attribute specified by
1863 	 * name.
1864 	 *
1865 	 * @param[in]  obj_hdl  File to look up
1866 	 * @param[in]  name     Name to look up
1867 	 * @param[out] xattr_id Number uniquely identifying the attribute
1868 	 *                      within the scope of the file
1869 	 *
1870 	 * @return FSAL status.
1871 	 */
1872 		 fsal_status_t (*getextattr_id_by_name)(struct fsal_obj_handle *obj_hdl,
1873 							const char *xattr_name,
1874 							unsigned int *xattr_id);
1875 	/**
1876 	 * @brief Get content of an attribute by name
1877 	 *
1878 	 * This function returns the value of an extended attribute as
1879 	 * specified by name.
1880 	 *
1881 	 * As a special rule, because it is implemented that way in the linux
1882 	 * getxattr call, giving a buffer_size of 0 is allowed and should set
1883 	 * output_size appropriately to fit the xattr.
1884 	 *
1885 	 * Please note that the xattr could change between the query-size call
1886 	 * and that actual fetch, so this is not fail-proof.
1887 	 *
1888 	 * @param[in]  obj_hdl     File to interrogate
1889 	 * @param[in]  xattr_name  Name of attribute
1890 	 * @param[out] buffer_addr Buffer to store content
1891 	 * @param[in]  buffer_size Buffer size
1892 	 * @param[out] output_size Size of content
1893 	 *
1894 	 * @return FSAL status.
1895 	 */
1896 		 fsal_status_t (*getextattr_value_by_name)(struct fsal_obj_handle *
1897 							   obj_hdl,
1898 							   const char *xattr_name,
1899 							   void *buffer_addr,
1900 							   size_t buffer_size,
1901 							   size_t *output_size);
1902 	
1903 	/**
1904 	 * @brief Get content of an attribute by id
1905 	 *
1906 	 * This function returns the value of an extended attribute as
1907 	 * specified by id.
1908 	 *
1909 	 * @param[in]  obj_hdl     File to interrogate
1910 	 * @param[in]  xattr_id    ID of attribute
1911 	 * @param[out] buffer_addr Buffer to store content
1912 	 * @param[in]  buffer_size Buffer size
1913 	 * @param[out] output_size Size of content
1914 	 *
1915 	 * @return FSAL status.
1916 	 */
1917 		 fsal_status_t (*getextattr_value_by_id)(struct fsal_obj_handle *
1918 							 obj_hdl,
1919 							 unsigned int xattr_id,
1920 							 void *buffer_addr,
1921 							 size_t buffer_size,
1922 							 size_t *output_size);
1923 	
1924 	/**
1925 	 * @brief Set content of an attribute
1926 	 *
1927 	 * This function sets the value of an extended attribute.
1928 	 *
1929 	 * @param[in] obj_hdl     File to modify
1930 	 * @param[in] xattr_name  Name of attribute
1931 	 * @param[in] buffer_addr Content to set
1932 	 * @param[in] buffer_size Content size
1933 	 * @param[in] create      true if attribute is to be created
1934 	 *
1935 	 * @return FSAL status.
1936 	 */
1937 		 fsal_status_t (*setextattr_value)(struct fsal_obj_handle *obj_hdl,
1938 						   const char *xattr_name,
1939 						   void *buffer_addr,
1940 						   size_t buffer_size, int create);
1941 	
1942 	/**
1943 	 * @brief Set content of an attribute by id
1944 	 *
1945 	 * This function sets the value of an extended attribute by id.
1946 	 *
1947 	 * @param[in] obj_hdl     File to modify
1948 	 * @param[in] xattr_id    ID of attribute
1949 	 * @param[in] buffer_addr Content to set
1950 	 * @param[in] buffer_size Content size
1951 	 *
1952 	 * @return FSAL status.
1953 	 */
1954 		 fsal_status_t (*setextattr_value_by_id)(struct fsal_obj_handle *
1955 							 obj_hdl,
1956 							 unsigned int xattr_id,
1957 							 void *buffer_addr,
1958 							 size_t buffer_size);
1959 	
1960 	/**
1961 	 * @brief Remove an extended attribute by id
1962 	 *
1963 	 * This function removes an extended attribute as specified by ID.
1964 	 *
1965 	 * @param[in] obj_hdl     File to modify
1966 	 * @param[in] xattr_id    ID of attribute
1967 	 *
1968 	 * @return FSAL status.
1969 	 */
1970 		 fsal_status_t (*remove_extattr_by_id)(struct fsal_obj_handle *obj_hdl,
1971 						       unsigned int xattr_id);
1972 	
1973 	/**
1974 	 * @brief Remove an extended attribute by name
1975 	 *
1976 	 * This function removes an extended attribute as specified by name.
1977 	 *
1978 	 * @param[in] obj_hdl     File to modify
1979 	 * @param[in] xattr_name  Name of attribute to remove
1980 	 *
1981 	 * @return FSAL status.
1982 	 */
1983 		 fsal_status_t (*remove_extattr_by_name)(struct fsal_obj_handle *
1984 							 obj_hdl,
1985 							 const char *xattr_name);
1986 	/**@}*/
1987 	
1988 	/**@{*/
1989 	/**
1990 	 * Handle operations
1991 	 */
1992 	
1993 	/**
1994 	 * @brief Write wire handle
1995 	 *
1996 	 * This function writes a "wire" handle or file ID to the given
1997 	 * buffer.
1998 	 *
1999 	 * @param[in]     obj_hdl     The handle to digest
2000 	 * @param[in]     output_type The type of digest to write
2001 	 * @param[in,out] fh_desc     Buffer descriptor to which to write
2002 	 *                            digest.  Set fh_desc->len to final
2003 	 *                            output length.
2004 	 *
2005 	 * @return FSAL status
2006 	 */
2007 		 fsal_status_t (*handle_to_wire)(const struct fsal_obj_handle *obj_hdl,
2008 						 fsal_digesttype_t output_type,
2009 						 struct gsh_buffdesc *fh_desc);
2010 	/**
2011 	 * @brief Get key for handle
2012 	 *
2013 	 * Indicate the unique part of the handle that should be used for
2014 	 * hashing.
2015 	 *
2016 	 * @param[in]  obj_hdl Handle whose key is to be got
2017 	 * @param[out] fh_desc Address and length giving sub-region of handle
2018 	 *                     to be used as key
2019 	 */
2020 		void (*handle_to_key)(struct fsal_obj_handle *obj_hdl,
2021 				      struct gsh_buffdesc *fh_desc);
2022 	/**
2023 	 * @brief Compare two handles
2024 	 *
2025 	 * This function compares two handles to see if they reference the same file
2026 	 *
2027 	 * @param[in]     obj_hdl1    The first handle to compare
2028 	 * @param[in]     obj_hdl2    The second handle to compare
2029 	 *
2030 	 * @return True if match, false otherwise
2031 	 */
2032 		 bool (*handle_cmp)(struct fsal_obj_handle *obj_hdl1,
2033 				    struct fsal_obj_handle *obj_hdl2);
2034 	/**@}*/
2035 	
2036 	/**@{*/
2037 	
2038 	/**
2039 	 * pNFS functions
2040 	 */
2041 	
2042 	/**
2043 	 * @brief Grant a layout segment.
2044 	 *
2045 	 * This function is called by nfs41_op_layoutget.  It may be called
2046 	 * multiple times, to satisfy a request with multiple segments.  The
2047 	 * FSAL may track state (what portion of the request has been or
2048 	 * remains to be satisfied or any other information it wishes) in the
2049 	 * bookkeeper member of res.  Each segment may have FSAL-specific
2050 	 * information associated with it its segid.  This segid will be
2051 	 * supplied to the FSAL when the segment is committed or returned.
2052 	 * When the granting the last segment it intends to grant, the FSAL
2053 	 * must set the last_segment flag in res.
2054 	 *
2055 	 * @param[in]     obj_hdl  The handle of the file on which the layout is
2056 	 *                         requested.
2057 	 * @param[in]     req_ctx  Request context
2058 	 * @param[out]    loc_body An XDR stream to which the FSAL must encode
2059 	 *                         the layout specific portion of the granted
2060 	 *                         layout segment.
2061 	 * @param[in]     arg      Input arguments of the function
2062 	 * @param[in,out] res      In/out and output arguments of the function
2063 	 *
2064 	 * @return Valid error codes in RFC 5661, pp. 366-7.
2065 	 */
2066 		 nfsstat4(*layoutget)(struct fsal_obj_handle *obj_hdl,
2067 				      struct req_op_context *req_ctx,
2068 				      XDR * loc_body,
2069 				      const struct fsal_layoutget_arg *arg,
2070 				      struct fsal_layoutget_res *res);
2071 	
2072 	/**
2073 	 * @brief Potentially return one layout segment
2074 	 *
2075 	 * This function is called once on each segment matching the IO mode
2076 	 * and intersecting the range specified in a LAYOUTRETURN operation or
2077 	 * for all layouts corresponding to a given stateid on last close,
2078 	 * leas expiry, or a layoutreturn with a return-type of FSID or ALL.
2079 	 * Whther it is called in the former or latter case is indicated by
2080 	 * the synthetic flag in the arg structure, with synthetic being true
2081 	 * in the case of last-close or lease expiry.
2082 	 *
2083 	 * If arg->dispose is true, all resources associated with the
2084 	 * layout must be freed.
2085 	 *
2086 	 * @param[in] obj_hdl  The object on which a segment is to be returned
2087 	 * @param[in] req_ctx  Request context
2088 	 * @param[in] lrf_body In the case of a non-synthetic return, this is
2089 	 *                     an XDR stream corresponding to the layout
2090 	 *                     type-specific argument to LAYOUTRETURN.  In
2091 	 *                     the case of a synthetic or bulk return,
2092 	 *                     this is a NULL pointer.
2093 	 * @param[in] arg      Input arguments of the function
2094 	 *
2095 	 * @return Valid error codes in RFC 5661, p. 367.
2096 	 */
2097 		 nfsstat4(*layoutreturn)(struct fsal_obj_handle *obj_hdl,
2098 					 struct req_op_context *req_ctx,
2099 					 XDR * lrf_body,
2100 					 const struct fsal_layoutreturn_arg *arg);
2101 	
2102 	/**
2103 	 * @brief Commit a segment of a layout
2104 	 *
2105 	 * This function is called once on every segment of a layout.  The
2106 	 * FSAL may avoid being called again after it has finished all tasks
2107 	 * necessary for the commit by setting res->commit_done to true.
2108 	 *
2109 	 * The calling function does not inspect or act on the value of
2110 	 * size_supplied or new_size until after the last call to
2111 	 * FSAL_layoutcommit.
2112 	 *
2113 	 * @param[in]     obj_hdl  The object on which to commit
2114 	 * @param[in]     req_ctx  Request context
2115 	 * @param[in]     lou_body An XDR stream containing the layout
2116 	 *                         type-specific portion of the LAYOUTCOMMIT
2117 	 *                         arguments.
2118 	 * @param[in]     arg      Input arguments of the function
2119 	 * @param[in,out] res      In/out and output arguments of the function
2120 	 *
2121 	 * @return Valid error codes in RFC 5661, p. 366.
2122 	 */
2123 		 nfsstat4(*layoutcommit)(struct fsal_obj_handle *obj_hdl,
2124 					 struct req_op_context *req_ctx,
2125 					 XDR * lou_body,
2126 					 const struct fsal_layoutcommit_arg *arg,
2127 					 struct fsal_layoutcommit_res *res);
2128 	
2129 	/**
2130 	 * @brief Get Extended Attribute
2131 	 *
2132 	 * This function gets an extended attribute of an object.
2133 	 *
2134 	 * @param[in]  obj_hdl  Input object to query
2135 	 * @param[in]  xa_name  Input xattr name
2136 	 * @param[out] xa_value Output xattr value
2137 	 *
2138 	 * @return FSAL status.
2139 	 */
2140 		 fsal_status_t (*getxattrs)(struct fsal_obj_handle *obj_hdl,
2141 					    xattrname4 *xa_name,
2142 					    xattrvalue4 *xa_value);
2143 	
2144 	/**
2145 	 * @brief Set Extended Attribute
2146 	 *
2147 	 * This function sets an extended attribute of an object.
2148 	 *
2149 	 * @param[in]  obj_hdl  Input object to set
2150 	 * @param[in]  xa_type  Input xattr type
2151 	 * @param[in]  xa_name  Input xattr name to set
2152 	 * @param[in]  xa_value Input xattr value to set
2153 	 *
2154 	 * @return FSAL status.
2155 	 */
2156 		 fsal_status_t (*setxattrs)(struct fsal_obj_handle *obj_hdl,
2157 					    setxattr_type4 sa_type,
2158 					    xattrname4 *xa_name,
2159 					    xattrvalue4 *xa_value);
2160 	
2161 	/**
2162 	 * @brief Remove Extended Attribute
2163 	 *
2164 	 * This function remove an extended attribute of an object.
2165 	 *
2166 	 * @param[in]  obj_hdl  Input object to set
2167 	 * @param[in]  xa_name  Input xattr name to remove
2168 	 *
2169 	 * @return FSAL status.
2170 	 */
2171 		 fsal_status_t (*removexattrs)(struct fsal_obj_handle *obj_hdl,
2172 					    xattrname4 *xa_name);
2173 	
2174 	/**
2175 	 * @brief List Extended Attributes
2176 	 *
2177 	 * This function list the extended attributes of an object.
2178 	 *
2179 	 * @param[in]      obj_hdl       Input object to list
2180 	 * @param[in]      la_maxcount   Input maximum number of bytes for names
2181 	 * @param[in,out]  la_cookie     In/out cookie
2182 	 * @param[in,out]  la_cookieverf In/out cookie verifier
2183 	 * @param[out]     lr_eof        Output eof set if no more extended attributes
2184 	 * @param[out]     lr_names      Output list of extended attribute names
2185 	 *				 this buffer size is double the size of
2186 	 *				 la_maxcount to allow for component4 overhead
2187 	 *
2188 	 * @return FSAL status.
2189 	 */
2190 		 fsal_status_t (*listxattrs)(struct fsal_obj_handle *obj_hdl,
2191 					     count4 la_maxcount,
2192 					     nfs_cookie4 *la_cookie,
2193 					     verifier4 *la_cookieverf,
2194 					     bool_t *lr_eof,
2195 					     xattrlist4 * lr_names);
2196 	
2197 	
2198 	/**@}*/
2199 	
2200 	/**@{*/
2201 	
2202 	/**
2203 	 * Extended API functions.
2204 	 *
2205 	 * With these new operations, the FSAL becomes responsible for managing
2206 	 * share reservations. The FSAL is also granted more control over the
2207 	 * state of a "file descriptor" and has more control of what a "file
2208 	 * descriptor" even is. Ultimately, it is whatever the FSAL needs in
2209 	 * order to manage the share reservations and lock state.
2210 	 *
2211 	 * The open2 method also allows atomic create/setattr/open (just like the
2212 	 * NFS v4 OPEN operation).
2213 	 *
2214 	 */
2215 	
2216 	/**
2217 	 * @brief Open a file descriptor for read or write and possibly create
2218 	 *
2219 	 * This function opens a file for read or write, possibly creating it.
2220 	 * If the caller is passing a state, it must hold the state_lock
2221 	 * exclusive.
2222 	 *
2223 	 * state can be NULL which indicates a stateless open (such as via the
2224 	 * NFS v3 CREATE operation), in which case the FSAL must assure protection
2225 	 * of any resources. If the file is being created, such protection is
2226 	 * simple since no one else will have access to the object yet, however,
2227 	 * in the case of an exclusive create, the common resources may still need
2228 	 * protection.
2229 	 *
2230 	 * If Name is NULL, obj_hdl is the file itself, otherwise obj_hdl is the
2231 	 * parent directory.
2232 	 *
2233 	 * On an exclusive create, the upper layer may know the object handle
2234 	 * already, so it MAY call with name == NULL. In this case, the caller
2235 	 * expects just to check the verifier.
2236 	 *
2237 	 * On a call with an existing object handle for an UNCHECKED create,
2238 	 * we can set the size to 0.
2239 	 *
2240 	 * At least the mode attribute must be set if createmode is not FSAL_NO_CREATE.
2241 	 * Some FSALs may still have to pass a mode on a create call for exclusive,
2242 	 * and even with FSAL_NO_CREATE, and empty set of attributes MUST be passed.
2243 	 *
2244 	 * If an open by name succeeds and did not result in Ganesha creating a file,
2245 	 * the caller will need to do a subsequent permission check to confirm the
2246 	 * open. This is because the permission attributes were not available
2247 	 * beforehand.
2248 	 *
2249 	 * The caller is expected to invoke fsal_release_attrs to release any
2250 	 * resources held by the set attributes. The FSAL layer MAY have added an
2251 	 * inherited ACL.
2252 	 *
2253 	 * The caller will set the request_mask in attrs_out to indicate the attributes
2254 	 * of interest. ATTR_ACL SHOULD NOT be requested and need not be provided. If
2255 	 * not all the requested attributes can be provided, this method MUST return
2256 	 * an error unless the ATTR_RDATTR_ERR bit was set in the request_mask.
2257 	 *
2258 	 * Since this method may instantiate a new fsal_obj_handle, it will be forced
2259 	 * to fetch at least some attributes in order to even know what the object
2260 	 * type is (as well as it's fileid and fsid). For this reason, the operation
2261 	 * as a whole can be expected to fail if the attributes were not able to be
2262 	 * fetched.
2263 	 *
2264 	 * The attributes will not be returned if this is an open by object as
2265 	 * opposed to an open by name.
2266 	 *
2267 	 * @note If the file was created, @a new_obj has been ref'd
2268 	 *
2269 	 * @param[in] obj_hdl               File to open or parent directory
2270 	 * @param[in,out] state             state_t to use for this operation
2271 	 * @param[in] openflags             Mode for open
2272 	 * @param[in] createmode            Mode for create
2273 	 * @param[in] name                  Name for file if being created or opened
2274 	 * @param[in] attrs_in              Attributes to set on created file
2275 	 * @param[in] verifier              Verifier to use for exclusive create
2276 	 * @param[in,out] new_obj           Newly created object
2277 	 * @param[in,out] attrs_out         Optional attributes for newly created object
2278 	 * @param[in,out] caller_perm_check The caller must do a permission check
2279 	 *
2280 	 * @return FSAL status.
2281 	 */
2282 		 fsal_status_t (*open2)(struct fsal_obj_handle *obj_hdl,
2283 					struct state_t *state,
2284 					fsal_openflags_t openflags,
2285 					enum fsal_create_mode createmode,
2286 					const char *name,
2287 					struct attrlist *attrs_in,
2288 					fsal_verifier_t verifier,
2289 					struct fsal_obj_handle **new_obj,
2290 					struct attrlist *attrs_out,
2291 					bool *caller_perm_check);
2292 	
2293 	/**
2294 	 * @brief Check the exclusive create verifier for a file.
2295 	 *
2296 	 * @param[in] obj_hdl     File to check verifier
2297 	 * @param[in] verifier    Verifier to use for exclusive create
2298 	 *
2299 	 * @retval true if verifier matches
2300 	 */
2301 		 bool (*check_verifier)(struct fsal_obj_handle *obj_hdl,
2302 					fsal_verifier_t verifier);
2303 	
2304 	/**
2305 	 * @brief Return open status of a state.
2306 	 *
2307 	 * This function returns open flags representing the current open
2308 	 * status for a state. The state_lock must be held.
2309 	 *
2310 	 * @param[in] obj_hdl     File owning state
2311 	 * @param[in] state File state to interrogate
2312 	 *
2313 	 * @retval Flags representing current open status
2314 	 */
2315 		fsal_openflags_t (*status2)(struct fsal_obj_handle *obj_hdl,
2316 					    struct state_t *state);
2317 	
2318 	/**
2319 	 * @brief Re-open a file that may be already opened
2320 	 *
2321 	 * This function supports changing the access mode of a share reservation and
2322 	 * thus should only be called with a share state. The state_lock must be held.
2323 	 *
2324 	 * This MAY be used to open a file the first time if there is no need for
2325 	 * open by name or create semantics. One example would be 9P lopen.
2326 	 *
2327 	 * @param[in] obj_hdl     File on which to operate
2328 	 * @param[in] state       state_t to use for this operation
2329 	 * @param[in] openflags   Mode for re-open
2330 	 *
2331 	 * @return FSAL status.
2332 	 */
2333 		 fsal_status_t (*reopen2)(struct fsal_obj_handle *obj_hdl,
2334 					  struct state_t *state,
2335 					  fsal_openflags_t openflags);
2336 	
2337 	/**
2338 	 * @brief Read data from a file
2339 	 *
2340 	 * This function reads data from the given file. The FSAL must be able to
2341 	 * perform the read whether a state is presented or not. This function also
2342 	 * is expected to handle properly bypassing or not share reservations.  This is
2343 	 * an (optionally) asynchronous call.  When the I/O is complete, the done
2344 	 * callback is called with the results.
2345 	 *
2346 	 * @param[in]     obj_hdl	File on which to operate
2347 	 * @param[in]     bypass	If state doesn't indicate a share reservation,
2348 	 *				bypass any deny read
2349 	 * @param[in,out] done_cb	Callback to call when I/O is done
2350 	 * @param[in,out] read_arg	Info about read, passed back in callback
2351 	 * @param[in,out] caller_arg	Opaque arg from the caller for callback
2352 	 *
2353 	 * @return Nothing; results are in callback
2354 	 */
2355 		 void (*read2)(struct fsal_obj_handle *obj_hdl,
2356 			       bool bypass,
2357 			       fsal_async_cb done_cb,
2358 			       struct fsal_io_arg *read_arg,
2359 			       void *caller_arg);
2360 	
2361 	/**
2362 	 * @brief Write data to a file
2363 	 *
2364 	 * This function writes data to a file. The FSAL must be able to
2365 	 * perform the write whether a state is presented or not. This function also
2366 	 * is expected to handle properly bypassing or not share reservations. Even
2367 	 * with bypass == true, it will enforce a mandatory (NFSv4) deny_write if
2368 	 * an appropriate state is not passed).
2369 	 *
2370 	 * The FSAL is expected to enforce sync if necessary.
2371 	 *
2372 	 * This is an (optionally) asynchronous call.  When the I/O is complete, the @a
2373 	 * done_cb callback is called.
2374 	 *
2375 	 * @param[in]     obj_hdl       File on which to operate
2376 	 * @param[in]     bypass        If state doesn't indicate a share reservation,
2377 	 *                              bypass any non-mandatory deny write
2378 	 * @param[in,out] done_cb	Callback to call when I/O is done
2379 	 * @param[in,out] write_arg	Info about write, passed back in callback
2380 	 * @param[in,out] caller_arg	Opaque arg from the caller for callback
2381 	 */
2382 		 void (*write2)(struct fsal_obj_handle *obj_hdl,
2383 				bool bypass,
2384 				fsal_async_cb done_cb,
2385 				struct fsal_io_arg *write_arg,
2386 				void *caller_arg);
2387 	
2388 	/**
2389 	 * @brief Seek to data or hole
2390 	 *
2391 	 * This function seek to data or hole in a file.
2392 	 *
2393 	 * @param[in]     obj_hdl   File on which to operate
2394 	 * @param[in]     state     state_t to use for this operation
2395 	 * @param[in,out] info      Information about the data
2396 	 *
2397 	 * @return FSAL status.
2398 	 */
2399 		 fsal_status_t (*seek2)(struct fsal_obj_handle *obj_hdl,
2400 					struct state_t *state,
2401 					struct io_info *info);
2402 	/**
2403 	 * @brief IO Advise
2404 	 *
2405 	 * This function give hints to fs.
2406 	 *
2407 	 * @param[in]     obj_hdl          File on which to operate
2408 	 * @param[in]     state            state_t to use for this operation
2409 	 * @param[in,out] info             Information about the data
2410 	 *
2411 	 * @return FSAL status.
2412 	 */
2413 		 fsal_status_t (*io_advise2)(struct fsal_obj_handle *obj_hdl,
2414 					     struct state_t *state,
2415 					     struct io_hints *hints);
2416 	
2417 	/**
2418 	 * @brief Commit written data
2419 	 *
2420 	 * This function flushes possibly buffered data to a file. This method
2421 	 * differs from commit due to the need to interact with share reservations
2422 	 * and the fact that the FSAL manages the state of "file descriptors". The
2423 	 * FSAL must be able to perform this operation without being passed a specific
2424 	 * state.
2425 	 *
2426 	 * @param[in] obj_hdl          File on which to operate
2427 	 * @param[in] state            state_t to use for this operation
2428 	 * @param[in] offset           Start of range to commit
2429 	 * @param[in] len              Length of range to commit
2430 	 *
2431 	 * @return FSAL status.
2432 	 */
2433 		 fsal_status_t (*commit2)(struct fsal_obj_handle *obj_hdl,
2434 					  off_t offset,
2435 					  size_t len);
2436 	
2437 	/**
2438 	 * @brief Perform a lock operation
2439 	 *
2440 	 * This function performs a lock operation (lock, unlock, test) on a
2441 	 * file. This method assumes the FSAL is able to support lock owners,
2442 	 * though it need not support asynchronous blocking locks. Passing the
2443 	 * lock state allows the FSAL to associate information with a specific
2444 	 * lock owner for each file (which may include use of a "file descriptor".
2445 	 *
2446 	 * @param[in]  obj_hdl          File on which to operate
2447 	 * @param[in]  state            state_t to use for this operation
2448 	 * @param[in]  owner            Lock owner
2449 	 * @param[in]  lock_op          Operation to perform
2450 	 * @param[in]  request_lock     Lock to take/release/test
2451 	 * @param[out] conflicting_lock Conflicting lock
2452 	 *
2453 	 * @return FSAL status.
2454 	 */
2455 		 fsal_status_t (*lock_op2)(struct fsal_obj_handle *obj_hdl,
2456 					   struct state_t *state,
2457 					   void *owner,
2458 					   fsal_lock_op_t lock_op,
2459 					   fsal_lock_param_t *request_lock,
2460 					   fsal_lock_param_t *conflicting_lock);
2461 	
2462 	/**
2463 	 * @brief Acquire or Release delegation
2464 	 *
2465 	 * This functions acquires/releases delegation/lease_lock.
2466 	 *
2467 	 * @param[in]  obj_hdl          File on which to operate
2468 	 * @param[in]  state            state_t to use for this operation
2469 	 * @param[in]  owner            Opaque state owner token
2470 	 * @param[in]  deleg            Requested delegation state
2471 	 *
2472 	 * @return FSAL status.
2473 	 */
2474 		 fsal_status_t (*lease_op2)(struct fsal_obj_handle *obj_hdl,
2475 					    struct state_t *state,
2476 					    void *owner,
2477 					    fsal_deleg_t deleg);
2478 	
2479 	/**
2480 	 * @brief Set attributes on an object
2481 	 *
2482 	 * This function sets attributes on an object.  Which attributes are
2483 	 * set is determined by attrib_set->mask. The FSAL must manage bypass
2484 	 * or not of share reservations, and a state may be passed.
2485 	 *
2486 	 * The caller is expected to invoke fsal_release_attrs to release any
2487 	 * resources held by the set attributes. The FSAL layer MAY have added an
2488 	 * inherited ACL.
2489 	 *
2490 	 * @param[in] obj_hdl    File on which to operate
2491 	 * @param[in] bypass     If state doesn't indicate a share reservation,
2492 	 *                       bypass any non-mandatory deny write
2493 	 * @param[in] state      state_t to use for this operation
2494 	 * @param[in] attrib_set Attributes to set
2495 	 *
2496 	 * @return FSAL status.
2497 	 */
2498 		 fsal_status_t (*setattr2)(struct fsal_obj_handle *obj_hdl,
2499 					   bool bypass,
2500 					   struct state_t *state,
2501 					   struct attrlist *attrib_set);
2502 	
2503 	/**
2504 	 * @brief Manage closing a file when a state is no longer needed.
2505 	 *
2506 	 * When the upper layers are ready to dispense with a state, this method is
2507 	 * called to allow the FSAL to close any file descriptors or release any other
2508 	 * resources associated with the state. A call to free_state should be assumed
2509 	 * to follow soon.
2510 	 *
2511 	 * @param[in] obj_hdl    File on which to operate
2512 	 * @param[in] state      state_t to use for this operation
2513 	 *
2514 	 * @return FSAL status.
2515 	 */
2516 		 fsal_status_t (*close2)(struct fsal_obj_handle *obj_hdl,
2517 					 struct state_t *state);
2518 	
2519 	/**@}*/
2520 	
2521 	/**
2522 	 * @brief Determine if the given handle is a referral point
2523 	 *
2524 	 * @param[in]	  obj_hdl	Handle on which to operate
2525 	 * @param[in|out] attrs		Attributes of the handle
2526 	 * @param[in]	  cache_attrs	Cache the received attrs
2527 	 *
2528 	 * @return true if it is a referral point, false otherwise
2529 	 */
2530 	
2531 		 bool (*is_referral)(struct fsal_obj_handle *obj_hdl,
2532 				     struct attrlist *attrs,
2533 				     bool cache_attrs);
2534 	
2535 	/**@{*/
2536 	
2537 	/**
2538 	 * ASYNC API functions.
2539 	 *
2540 	 * These are asyncronous versions of some of the API functions.  FSALs are
2541 	 * expected to implement these, but the upper layers are not expected to call
2542 	 * them.  Instead, they will be called by MDCACHE at the appropriate points.
2543 	 */
2544 	
2545 	/**@}*/
2546 	};
2547 	
2548 	/**
2549 	 * @brief FSAL pNFS Data Server operations vector
2550 	 */
2551 	
2552 	struct fsal_pnfs_ds_ops {
2553 	/**@{*/
2554 	
2555 	/**
2556 	 * Lifecycle management.
2557 	 */
2558 	
2559 	/**
2560 	 * @brief Clean up a server
2561 	 *
2562 	 * This function cleans up private resources associated with a
2563 	 * server and deallocates it.  A default is supplied.
2564 	 *
2565 	 * This function should not be called directly.
2566 	 *
2567 	 * @param[in]  pds	FSAL pNFS DS to release
2568 	 */
2569 		 void (*release)(struct fsal_pnfs_ds *const pds);
2570 	
2571 	/**
2572 	 * @brief Initialize FSAL specific permissions per pNFS DS
2573 	 *
2574 	 * @param[in]  pds      FSAL pNFS DS
2575 	 * @param[in]  req      Incoming request.
2576 	 *
2577 	 * @return NFSv4.1 error codes:
2578 	 *			NFS4_OK, NFS4ERR_ACCESS, NFS4ERR_WRONGSEC.
2579 	 */
2580 		 nfsstat4(*permissions)(struct fsal_pnfs_ds *const pds,
2581 					struct svc_req *req);
2582 	/**@}*/
2583 	
2584 	/**@{*/
2585 	
2586 	/**
2587 	 * @brief Create a FSAL data server handle from a wire handle
2588 	 *
2589 	 * This function creates a FSAL data server handle from a client
2590 	 * supplied "wire" handle.
2591 	 *
2592 	 * @param[in]  pds      FSAL pNFS DS
2593 	 * @param[in]  hdl_desc Buffer from which to create the struct
2594 	 * @param[out] handle   FSAL DS handle
2595 	 *
2596 	 * @return NFSv4.1 error codes.
2597 	 */
2598 		 nfsstat4(*make_ds_handle)(struct fsal_pnfs_ds *const pds,
2599 					   const struct gsh_buffdesc *
2600 					   const hdl_desc,
2601 					   struct fsal_ds_handle **const handle,
2602 					   int flags);
2603 	
2604 	/**
2605 	 * @brief Initialize FSAL specific values for DS handle
2606 	 *
2607 	 * @param[in]  ops	FSAL DS handle operations vector
2608 	 */
2609 		 void (*fsal_dsh_ops)(struct fsal_dsh_ops *ops);
2610 	
2611 	/**@}*/
2612 	};
2613 	
2614 	/**
2615 	 * @brief FSAL DS handle operations vector
2616 	 */
2617 	
2618 	struct fsal_dsh_ops {
2619 	/**@{*/
2620 	
2621 	/**
2622 	 * Lifecycle management.
2623 	 */
2624 	
2625 	/**
2626 	 * @brief Clean up a DS handle
2627 	 *
2628 	 * This function cleans up private resources associated with a
2629 	 * filehandle and deallocates it.  Implement this method or you will
2630 	 * leak.  This function should not be called directly.
2631 	 *
2632 	 * @param[in] ds_hdl Handle to release
2633 	 */
2634 		 void (*release)(struct fsal_ds_handle *const ds_hdl);
2635 	/**@}*/
2636 	
2637 	/**@{*/
2638 	
2639 	/**
2640 	 * I/O Functions
2641 	 */
2642 	
2643 	/**
2644 	 * @brief Read from a data-server handle.
2645 	 *
2646 	 * NFSv4.1 data server handles are disjount from normal
2647 	 * filehandles (in Ganesha, there is a ds_flag in the filehandle_v4_t
2648 	 * structure) and do not get loaded into cache_inode or processed the
2649 	 * normal way.
2650 	 *
2651 	 * @param[in]  ds_hdl           FSAL DS handle
2652 	 * @param[in]  req_ctx          Credentials
2653 	 * @param[in]  stateid          The stateid supplied with the READ operation,
2654 	 *                              for validation
2655 	 * @param[in]  offset           The offset at which to read
2656 	 * @param[in]  requested_length Length of read requested (and size of buffer)
2657 	 * @param[out] buffer           The buffer to which to store read data
2658 	 * @param[out] supplied_length  Length of data read
2659 	 * @param[out] eof              true on end of file
2660 	 *
2661 	 * @return An NFSv4.1 status code.
2662 	 */
2663 		 nfsstat4(*read)(struct fsal_ds_handle *const ds_hdl,
2664 				 struct req_op_context *const req_ctx,
2665 				 const stateid4 * stateid,
2666 				 const offset4 offset,
2667 				 const count4 requested_length,
2668 				 void *const buffer,
2669 				 count4 * const supplied_length,
2670 				 bool *const end_of_file);
2671 	
2672 	/**
2673 	 * @brief Read plus from a data-server handle.
2674 	 *
2675 	 * NFSv4.2 data server handles are disjount from normal
2676 	 * filehandles (in Ganesha, there is a ds_flag in the filehandle_v4_t
2677 	 * structure) and do not get loaded into cache_inode or processed the
2678 	 * normal way.
2679 	 *
2680 	 * @param[in]  ds_hdl           FSAL DS handle
2681 	 * @param[in]  req_ctx          Credentials
2682 	 * @param[in]  stateid          The stateid supplied with the READ operation,
2683 	 *                              for validation
2684 	 * @param[in]  offset           The offset at which to read
2685 	 * @param[in]  requested_length Length of read requested (and size of buffer)
2686 	 * @param[out] buffer           The buffer to which to store read data
2687 	 * @param[out] supplied_length  Length of data read
2688 	 * @param[out] eof              true on end of file
2689 	 * @param[out] info             IO info
2690 	 *
2691 	 * @return An NFSv4.2 status code.
2692 	 */
2693 		 nfsstat4(*read_plus)(struct fsal_ds_handle *const ds_hdl,
2694 				      struct req_op_context *const req_ctx,
2695 				      const stateid4 * stateid,
2696 				      const offset4 offset,
2697 				      const count4 requested_length,
2698 				      void *const buffer,
2699 				      const count4 supplied_length,
2700 				      bool *const end_of_file,
2701 				      struct io_info *info);
2702 	
2703 	/**
2704 	 *
2705 	 * @brief Write to a data-server handle.
2706 	 *
2707 	 * NFSv4.1 data server filehandles are disjount from normal
2708 	 * filehandles (in Ganesha, there is a ds_flag in the filehandle_v4_t
2709 	 * structure) and do not get loaded into cache_inode or processed the
2710 	 * normal way.
2711 	 *
2712 	 * @param[in]  ds_hdl           FSAL DS handle
2713 	 * @param[in]  req_ctx          Credentials
2714 	 * @param[in]  stateid          The stateid supplied with the READ operation,
2715 	 *                              for validation
2716 	 * @param[in]  offset           The offset at which to read
2717 	 * @param[in]  write_length     Length of write requested (and size of buffer)
2718 	 * @param[out] buffer           The buffer to which to store read data
2719 	 * @param[in]  stability wanted Stability of write
2720 	 * @param[out] written_length   Length of data written
2721 	 * @param[out] writeverf        Write verifier
2722 	 * @param[out] stability_got    Stability used for write (must be as
2723 	 *                              or more stable than request)
2724 	 *
2725 	 * @return An NFSv4.1 status code.
2726 	 */
2727 		 nfsstat4(*write)(struct fsal_ds_handle *const ds_hdl,
2728 				  struct req_op_context *const req_ctx,
2729 				  const stateid4 * stateid,
2730 				  const offset4 offset,
2731 				  const count4 write_length,
2732 				  const void *buffer,
2733 				  const stable_how4 stability_wanted,
2734 				  count4 * const written_length,
2735 				  verifier4 * const writeverf,
2736 				  stable_how4 * const stability_got);
2737 	
2738 	/**
2739 	 * @brief Commit a byte range to a DS handle.
2740 	 *
2741 	 * NFSv4.1 data server filehandles are disjount from normal
2742 	 * filehandles (in Ganesha, there is a ds_flag in the filehandle_v4_t
2743 	 * structure) and do not get loaded into cache_inode or processed the
2744 	 * normal way.
2745 	 *
2746 	 * @param[in]  ds_hdl    FSAL DS handle
2747 	 * @param[in]  req_ctx   Credentials
2748 	 * @param[in]  offset    Start of commit window
2749 	 * @param[in]  count     Length of commit window
2750 	 * @param[out] writeverf Write verifier
2751 	 *
2752 	 * @return An NFSv4.1 status code.
2753 	 */
2754 		 nfsstat4(*commit)(struct fsal_ds_handle *const ds_hdl,
2755 				   struct req_op_context *const req_ctx,
2756 				   const offset4 offset,
2757 				   const count4 count,
2758 				   verifier4 * const writeverf);
2759 	/**@}*/
2760 	};
2761 	
2762 	/**
2763 	 * @brief FSAL object definition
2764 	 *
2765 	 * This structure is the base FSAL instance definition, providing the
2766 	 * public face to a single, loaded FSAL.
2767 	 */
2768 	
2769 	struct fsal_module {
2770 		struct glist_head fsals;	/*< link in list of loaded fsals */
2771 		struct glist_head exports;	/*< Head of list of exports from
2772 						   this FSAL */
2773 		struct glist_head handles;	/*< Head of list of object handles */
2774 		struct glist_head servers;	/*< Head of list of Data Servers */
2775 		char *path;		/*< Path to .so file */
2776 		char *name;		/*< Name set from .so and/or config */
2777 		void *dl_handle;	/*< Handle to the dlopen()d shared
2778 					   library. NULL if statically linked */
2779 		struct fsal_ops m_ops;	/*< FSAL module methods vector */
2780 	
2781 		pthread_rwlock_t lock;		/*< Lock to be held when
2782 						    manipulating its lists (above). */
2783 		int32_t refcount;		/*< Reference count */
2784 		struct fsal_stats *stats;   /*< for storing the FSAL specific stats */
2785 		struct fsal_staticfsinfo_t fs_info; /*< for storing FSAL static info */
2786 	};
2787 	
2788 	/**
2789 	 * @brief Get a reference to a module
2790 	 *
2791 	 * @param[in] fsal_hdl FSAL on which to acquire reference.
2792 	 */
2793 	
2794 	static inline void fsal_get(struct fsal_module *fsal_hdl)
2795 	{
2796 		(void) atomic_inc_int32_t(&fsal_hdl->refcount);
2797 		assert(fsal_hdl->refcount > 0);
2798 	}
2799 	
2800 	/**
2801 	 * @brief Relinquish a reference to the module
2802 	 *
2803 	 * This function relinquishes one reference to the FSAL.  After the
2804 	 * reference count falls to zero, the FSAL may be freed and unloaded.
2805 	 *
2806 	 * @param[in] fsal_hdl FSAL on which to release reference.
2807 	 */
2808 	
2809 	static inline void fsal_put(struct fsal_module *fsal_hdl)
2810 	{
2811 		int32_t refcount;
2812 	
2813 		refcount = atomic_dec_int32_t (&fsal_hdl->refcount);
2814 	
2815 		assert(refcount >= 0);
2816 	
2817 		if (refcount == 0) {
2818 			LogInfo(COMPONENT_FSAL,
2819 				"FSAL %s now unused",
2820 				fsal_hdl->name);
2821 		}
2822 	}
2823 	
2824 	/**
2825 	 * @brief Export object
2826 	 *
2827 	 * This structure is created by the @c create_export method on the
2828 	 * FSAL module.  It is stored as part of the export list and is used
2829 	 * to manage individual exports, interrogate properties of the
2830 	 * filesystem, and create individual file handle objects.
2831 	 */
2832 	
2833 	struct fsal_export {
2834 		struct glist_head exports;	/*< Link in list of exports from
2835 						   the same FSAL. */
2836 		struct fsal_module *fsal;	/*< Link back to the FSAL module */
2837 		const struct fsal_up_vector *up_ops;	/*< Upcall operations */
2838 		struct export_ops exp_ops;	/*< Vector of operations */
2839 		struct fsal_export *sub_export;	/*< Sub export for stacking */
2840 		struct fsal_export *super_export;/*< Super export for stacking */
2841 		uint16_t export_id; /*< Export ID copied from gsh_export, initialized
2842 					by  fsal_export_init */
2843 	};
2844 	
2845 	/**
2846 	 * @brief Public structure for filesystem descriptions
2847 	 *
2848 	 * This stucture is provided along with a general interface to support those
2849 	 * FSALs that map into a traditional file system model. Note that
2850 	 * fsal_obj_handles do not link to an fsal_filesystem, that linkage is reserved
2851 	 * for FSAL's private obj handle if appropriate.
2852 	 *
2853 	 */
2854 	
2855 	struct fsal_filesystem {
2856 		struct glist_head filesystems;	/*< List of file systems */
2857 		struct glist_head children;	/*< Child file systems */
2858 		struct glist_head siblings;	/*< Entry in list of parent's child
2859 						    file systems */
2860 		struct fsal_filesystem *parent;	/*< Parent file system */
2861 		struct fsal_module *fsal;	/*< Link back to fsal module */
2862 		void *private_data;		/*< Private data for owning FSAL */
2863 		char *path;			/*< Path to root of this file system */
2864 		char *device;			/*< Path to block device */
2865 		char *type;			/*< fs type */
2866 	
2867 		unclaim_filesystem_cb unclaim;  /*< Call back to unclaim this fs */
2868 		uint32_t pathlen;		/*< Length of path */
2869 		uint32_t namelen;		/*< Name length from statfs */
2870 	
2871 		struct avltree_node avl_fsid;	/*< AVL indexed by fsid */
2872 		struct avltree_node avl_dev;	/*< AVL indexed by dev */
2873 		struct fsal_fsid__ fsid;	/*< file system id */
2874 		fsal_dev_t dev;			/*< device filesystem is on */
2875 		enum fsid_type fsid_type;	/*< type of fsid present */
2876 		bool in_fsid_avl;		/*< true if inserted in fsid avl */
2877 		bool in_dev_avl;		/*< true if inserted in dev avl */
2878 		bool exported;			/*< true if explicitly exported */
2879 	};
2880 	
2881 	/**
2882 	 * @brief Public structure for filesystem objects
2883 	 *
2884 	 * This structure is used for files of all types including directories
2885 	 * and anything else that can be operated on via NFS.
2886 	 *
2887 	 * All functions that create a a new object handle should allocate
2888 	 * memory for the complete (public and private) handle and perform any
2889 	 * private initialization.  They should fill the
2890 	 * @c fsal_obj_handle::attributes structure.  They should also call the
2891 	 * @c fsal_obj_handle_init function with the public object handle,
2892 	 * object handle operations vector, public export, and file type.
2893 	 *
2894 	 * @note Do we actually need a lock and ref count on the fsal object
2895 	 * handle, since cache_inode is managing life cycle and concurrency?
2896 	 * That is, do we expect fsal_obj_handle to have a reference count
2897 	 * that would be separate from that managed by cache_inode_lru?
2898 	 */
2899 	
2900 	struct fsal_obj_handle {
2901 		struct glist_head handles;	/*< Link in list of handles under
2902 						   the same FSAL. */
2903 		struct fsal_filesystem *fs;	/*< Owning filesystem */
2904 		struct fsal_module *fsal;	/*< Link back to fsal module */
2905 		struct fsal_obj_ops *obj_ops;	/*< Operations vector */
2906 	
2907 		pthread_rwlock_t obj_lock;		/*< Lock on handle */
2908 	
2909 		/* Static attributes */
2910 		object_file_type_t type;	/*< Object file type */
2911 		fsal_fsid_t fsid;	/*< Filesystem on which this object is
2912 					   stored */
2913 		uint64_t fileid;	/*< Unique identifier for this object within
2914 					   the scope of the fsid, (e.g. inode number) */
2915 	
2916 		struct state_hdl *state_hdl;	/*< State related to this handle */
2917 	};
2918 	
2919 	/**
2920 	 * @brief Public structure for pNFS Data Servers
2921 	 *
2922 	 * This structure is used for files of all types including directories
2923 	 * and anything else that can be operated on via NFS.  Having an
2924 	 * independent reference count and lock here makes sense, since there
2925 	 * is no caching infrastructure overlaying this system.
2926 	 *
2927 	 */
2928 	
2929 	enum pnfs_ds_status {
2930 		PNFS_DS_READY,			/*< searchable, usable */
2931 		PNFS_DS_STALE,			/*< is no longer valid */
2932 	};
2933 	
2934 	/**
2935 	 * @brief PNFS Data Server
2936 	 *
2937 	 * This represents a Data Server for PNFS.  It may be stand-alone, or may be
2938 	 * associated with an export (which represents an MDS).
2939 	 */
2940 	struct fsal_pnfs_ds {
2941 		struct glist_head ds_list;	/**< Entry in list of all DSs */
2942 		struct glist_head server;	/**< Link in list of Data Servers under
2943 						   the same FSAL. */
2944 		struct glist_head ds_handles;	/**< Head of list of DS handles */
2945 		struct fsal_module *fsal;	/**< Link back to fsal module */
2946 		struct fsal_pnfs_ds_ops s_ops;	/**< Operations vector */
2947 		struct gsh_export *mds_export;	/**< related export */
2948 		struct fsal_export *mds_fsal_export;	/**< related FSAL export (avoids
2949 							  MDS stacking) */
2950 	
2951 		struct avltree_node ds_node;	/**< Node in tree of all Data Servers */
2952 		pthread_rwlock_t lock;		/**< Lock to be held when
2953 						    manipulating its list (above). */
2954 		int32_t refcount;		/**< Reference count */
2955 		uint16_t id_servers;		/**< Identifier */
2956 		uint8_t pnfs_ds_status;		/**< current condition */
2957 	};
2958 	
2959 	/**
2960 	 * @brief Public structure for DS file handles
2961 	 *
2962 	 * This structure is used for files of all types including directories
2963 	 * and anything else that can be operated on via NFS.  Having an
2964 	 * independent reference count and lock here makes sense, since there
2965 	 * is no caching infrastructure overlaying this system.
2966 	 *
2967 	 */
2968 	
2969 	struct fsal_ds_handle {
2970 		struct glist_head ds_handle;	/*< Link in list of DS handles under
2971 						   the same pDS. */
2972 		struct fsal_pnfs_ds *pds;	/*< Link back to pDS */
2973 		struct fsal_dsh_ops dsh_ops;	/*< Operations vector */
2974 	
2975 		int64_t refcount;		/*< Reference count */
2976 	};
2977 	
2978 	/**
2979 	 * @brief Get a reference on a DS handle
2980 	 *
2981 	 * This function increments the reference count on a DS handle.
2982 	 *
2983 	 * @param[in] ds_hdl The handle to reference
2984 	 */
2985 	
2986 	static inline void ds_handle_get_ref(struct fsal_ds_handle *const ds_hdl)
2987 	{
2988 		(void) atomic_inc_int64_t (&ds_hdl->refcount);
2989 	}
2990 	
2991 	/**
2992 	 * @brief Release a reference on a DS handle
2993 	 *
2994 	 * This function releases a reference to a DS handle.  Once a caller's
2995 	 * reference is released they should make no attempt to access the
2996 	 * handle or even dereference a pointer to it.
2997 	 *
2998 	 * @param[in] ds_hdl The handle to relinquish
2999 	 */
3000 	
3001 	static inline void ds_handle_put(struct fsal_ds_handle *const ds_hdl)
3002 	{
3003 		int64_t refcount = atomic_dec_int64_t (&ds_hdl->refcount);
3004 	
3005 		if (refcount != 0) {
3006 			assert(refcount > 0);
3007 			return;
3008 		}
3009 	
3010 		ds_hdl->dsh_ops.release(ds_hdl);
3011 	}
3012 	
3013 	/**
3014 	** Resolve forward declarations
3015 	*/
3016 	#include "client_mgr.h"
(1) Event include_recursion: #include file "/home/kkeithle/src/github/kaleb2/nfs-ganesha/src/include/export_mgr.h" includes itself: export_mgr.h -> fsal.h -> fsal_api.h -> export_mgr.h
(2) Event caretline: ^
3017 	#include "export_mgr.h"
3018 	#include "fsal_up.h"
3019 	
3020 	#endif				/* !FSAL_API */
3021 	/** @} */
3022