1 /* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
2 * vim:expandtab:shiftwidth=8:tabstop=8:
4 * Copyright (C) 2006 Cluster File Systems, Inc.
6 * This file is part of Lustre, http://www.lustre.org.
8 * Lustre is free software; you can redistribute it and/or
9 * modify it under the terms of version 2 of the GNU General Public
10 * License as published by the Free Software Foundation.
12 * Lustre is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with Lustre; if not, write to the Free Software
19 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
23 #ifndef __LUSTRE_DT_OBJECT_H
24 #define __LUSTRE_DT_OBJECT_H
27 * Sub-class of lu_object with methods common for "data" objects in OST stack.
29 * Data objects behave like regular files: you can read/write them, get and
30 * set their attributes. Implementation of dt interface is supposed to
31 * implement some form of garbage collection, normally reference counting
34 * Examples: osd (lustre/osd) is an implementation of dt interface.
39 * super-class definitions.
41 #include <lu_object.h>
43 #include <libcfs/list.h>
44 #include <libcfs/kp30.h>
47 struct proc_dir_entry;
54 struct dt_index_features;
56 struct dt_device_param {
57 unsigned ddp_max_name_len;
58 unsigned ddp_max_nlink;
59 unsigned ddp_block_shift;
63 * Basic transaction credit op
73 DTO_LOG_REC, /* XXX temporary: dt layer knows nothing about llog. */
79 * Operations on dt device.
81 struct dt_device_operations {
83 * Return device-wide statistics.
85 int (*dt_statfs)(const struct lu_env *env,
86 struct dt_device *dev, struct kstatfs *sfs);
88 * Start transaction, described by @param.
90 struct thandle *(*dt_trans_start)(const struct lu_env *env,
91 struct dt_device *dev,
92 struct txn_param *param);
94 * Finish previously started transaction.
96 void (*dt_trans_stop)(const struct lu_env *env,
99 * Return fid of root index object.
101 int (*dt_root_get)(const struct lu_env *env,
102 struct dt_device *dev, struct lu_fid *f);
104 * Return device configuration data.
106 void (*dt_conf_get)(const struct lu_env *env,
107 const struct dt_device *dev,
108 struct dt_device_param *param);
110 * handling device state, mostly for tests
112 int (*dt_sync)(const struct lu_env *env, struct dt_device *dev);
113 void (*dt_ro)(const struct lu_env *env, struct dt_device *dev);
115 * Initialize capability context.
117 int (*dt_init_capa_ctxt)(const struct lu_env *env,
118 struct dt_device *dev,
119 int mode, unsigned long timeout,
120 __u32 alg, struct lustre_capa_key *keys);
123 * get transaction credits for given @op.
125 int (*dt_credit_get)(const struct lu_env *env, struct dt_device *dev,
129 struct dt_index_features {
130 /* required feature flags from enum dt_index_flags */
132 /* minimal required key size */
133 size_t dif_keysize_min;
134 /* maximal required key size, 0 if no limit */
135 size_t dif_keysize_max;
136 /* minimal required record size */
137 size_t dif_recsize_min;
138 /* maximal required record size, 0 if no limit */
139 size_t dif_recsize_max;
142 enum dt_index_flags {
143 /* index supports variable sized keys */
144 DT_IND_VARKEY = 1 << 0,
145 /* index supports variable sized records */
146 DT_IND_VARREC = 1 << 1,
147 /* index can be modified */
148 DT_IND_UPDATE = 1 << 2,
149 /* index supports records with non-unique (duplicate) keys */
150 DT_IND_NONUNQ = 1 << 3
154 * Features, required from index to support file system directories (mapping
157 extern const struct dt_index_features dt_directory_features;
160 * This is a general purpose dt allocation hint.
161 * It now contains the parent object.
162 * It can contain any allocation hint in the future.
164 struct dt_allocation_hint {
165 struct dt_object *dah_parent;
170 * Per-dt-object operations.
172 struct dt_object_operations {
173 void (*do_read_lock)(const struct lu_env *env,
174 struct dt_object *dt);
175 void (*do_write_lock)(const struct lu_env *env,
176 struct dt_object *dt);
177 void (*do_read_unlock)(const struct lu_env *env,
178 struct dt_object *dt);
179 void (*do_write_unlock)(const struct lu_env *env,
180 struct dt_object *dt);
182 * Note: following ->do_{x,}attr_{set,get}() operations are very
183 * similar to ->moo_{x,}attr_{set,get}() operations in struct
184 * md_object_operations (see md_object.h). These operations are not in
185 * lu_object_operations, because ->do_{x,}attr_set() versions take
186 * transaction handle as an argument (this transaction is started by
187 * caller). We might factor ->do_{x,}attr_get() into
188 * lu_object_operations, but that would break existing symmetry.
192 * Return standard attributes.
194 * precondition: lu_object_exists(&dt->do_lu);
196 int (*do_attr_get)(const struct lu_env *env,
197 struct dt_object *dt, struct lu_attr *attr,
198 struct lustre_capa *capa);
200 * Set standard attributes.
202 * precondition: dt_object_exists(dt);
204 int (*do_attr_set)(const struct lu_env *env,
205 struct dt_object *dt,
206 const struct lu_attr *attr,
207 struct thandle *handle,
208 struct lustre_capa *capa);
210 * Return a value of an extended attribute.
212 * precondition: dt_object_exists(dt);
214 int (*do_xattr_get)(const struct lu_env *env, struct dt_object *dt,
215 struct lu_buf *buf, const char *name,
216 struct lustre_capa *capa);
218 * Set value of an extended attribute.
220 * @fl - flags from enum lu_xattr_flags
222 * precondition: dt_object_exists(dt);
224 int (*do_xattr_set)(const struct lu_env *env,
225 struct dt_object *dt, const struct lu_buf *buf,
226 const char *name, int fl, struct thandle *handle,
227 struct lustre_capa *capa);
229 * Delete existing extended attribute.
231 * precondition: dt_object_exists(dt);
233 int (*do_xattr_del)(const struct lu_env *env,
234 struct dt_object *dt,
235 const char *name, struct thandle *handle,
236 struct lustre_capa *capa);
238 * Place list of existing extended attributes into @buf (which has
241 * precondition: dt_object_exists(dt);
243 int (*do_xattr_list)(const struct lu_env *env,
244 struct dt_object *dt, struct lu_buf *buf,
245 struct lustre_capa *capa);
247 * Init allocation hint using parent object and child mode.
248 * (1) The @parent might be NULL if this is a partial creation for
250 * (2) The type of child is in @child_mode.
251 * (3) The result hint is stored in @ah;
253 void (*do_ah_init)(const struct lu_env *env,
254 struct dt_allocation_hint *ah,
255 struct dt_object *parent,
258 * Create new object on this device.
260 * precondition: !dt_object_exists(dt);
261 * postcondition: ergo(result == 0, dt_object_exists(dt));
263 int (*do_create)(const struct lu_env *env, struct dt_object *dt,
264 struct lu_attr *attr,
265 struct dt_allocation_hint *hint,
269 * Announce that this object is going to be used as an index. This
270 * operation check that object supports indexing operations and
271 * installs appropriate dt_index_operations vector on success.
273 * Also probes for features. Operation is successful if all required
274 * features are supported.
276 int (*do_index_try)(const struct lu_env *env,
277 struct dt_object *dt,
278 const struct dt_index_features *feat);
280 * Add nlink of the object
281 * precondition: dt_object_exists(dt);
283 void (*do_ref_add)(const struct lu_env *env,
284 struct dt_object *dt, struct thandle *th);
286 * Del nlink of the object
287 * precondition: dt_object_exists(dt);
289 void (*do_ref_del)(const struct lu_env *env,
290 struct dt_object *dt, struct thandle *th);
292 struct obd_capa *(*do_capa_get)(const struct lu_env *env,
293 struct dt_object *dt,
294 struct lustre_capa *old,
295 __u32 uid, __u64 opc);
299 * Per-dt-object operations on "file body".
301 struct dt_body_operations {
303 * precondition: dt_object_exists(dt);
305 ssize_t (*dbo_read)(const struct lu_env *env, struct dt_object *dt,
306 struct lu_buf *buf, loff_t *pos,
307 struct lustre_capa *capa);
309 * precondition: dt_object_exists(dt);
311 ssize_t (*dbo_write)(const struct lu_env *env, struct dt_object *dt,
312 const struct lu_buf *buf, loff_t *pos,
313 struct thandle *handle, struct lustre_capa *capa);
317 * Incomplete type of index record.
322 * Incomplete type of index key.
327 * Incomplete type of dt iterator.
332 * Per-dt-object operations on object as index.
334 struct dt_index_operations {
336 * precondition: dt_object_exists(dt);
338 int (*dio_lookup)(const struct lu_env *env, struct dt_object *dt,
339 struct dt_rec *rec, const struct dt_key *key,
340 struct lustre_capa *capa);
342 * precondition: dt_object_exists(dt);
344 int (*dio_insert)(const struct lu_env *env, struct dt_object *dt,
345 const struct dt_rec *rec, const struct dt_key *key,
346 struct thandle *handle, struct lustre_capa *capa);
348 * precondition: dt_object_exists(dt);
350 int (*dio_delete)(const struct lu_env *env, struct dt_object *dt,
351 const struct dt_key *key, struct thandle *handle,
352 struct lustre_capa *capa);
358 * Allocate and initialize new iterator.
360 * precondition: dt_object_exists(dt);
362 struct dt_it *(*init)(const struct lu_env *env,
363 struct dt_object *dt, int writable,
364 struct lustre_capa *capa);
365 void (*fini)(const struct lu_env *env,
367 int (*get)(const struct lu_env *env,
369 const struct dt_key *key);
370 void (*put)(const struct lu_env *env,
372 int (*del)(const struct lu_env *env,
373 struct dt_it *di, struct thandle *th);
374 int (*next)(const struct lu_env *env,
376 struct dt_key *(*key)(const struct lu_env *env,
377 const struct dt_it *di);
378 int (*key_size)(const struct lu_env *env,
379 const struct dt_it *di);
380 struct dt_rec *(*rec)(const struct lu_env *env,
381 const struct dt_it *di);
382 __u32 (*store)(const struct lu_env *env,
383 const struct dt_it *di);
384 int (*load)(const struct lu_env *env,
385 const struct dt_it *di, __u32 hash);
390 struct lu_device dd_lu_dev;
391 struct dt_device_operations *dd_ops;
394 * List of dt_txn_callback (see below). This is not protected in any
395 * way, because callbacks are supposed to be added/deleted only during
396 * single-threaded start-up shut-down procedures.
398 struct list_head dd_txn_callbacks;
401 int dt_device_init(struct dt_device *dev, struct lu_device_type *t);
402 void dt_device_fini(struct dt_device *dev);
404 static inline int lu_device_is_dt(const struct lu_device *d)
406 return ergo(d != NULL, d->ld_type->ldt_tags & LU_DEVICE_DT);
409 static inline struct dt_device * lu2dt_dev(struct lu_device *l)
411 LASSERT(lu_device_is_dt(l));
412 return container_of0(l, struct dt_device, dd_lu_dev);
416 struct lu_object do_lu;
417 struct dt_object_operations *do_ops;
418 struct dt_body_operations *do_body_ops;
419 struct dt_index_operations *do_index_ops;
422 int dt_object_init(struct dt_object *obj,
423 struct lu_object_header *h, struct lu_device *d);
425 void dt_object_fini(struct dt_object *obj);
427 static inline int dt_object_exists(const struct dt_object *dt)
429 return lu_object_exists(&dt->do_lu);
433 /* number of blocks this transaction will modify */
434 unsigned int tp_credits;
435 /* sync transaction is needed */
439 static inline void txn_param_init(struct txn_param *p, unsigned int credits)
441 memset(p, 0, sizeof(*p));
442 p->tp_credits = credits;
446 * This is the general purpose transaction handle.
447 * 1. Transaction Life Cycle
448 * This transaction handle is allocated upon starting a new transaction,
449 * and deallocated after this transaction is committed.
450 * 2. Transaction Nesting
451 * We do _NOT_ support nested transaction. So, every thread should only
452 * have one active transaction, and a transaction only belongs to one
453 * thread. Due to this, transaction handle need no reference count.
454 * 3. Transaction & dt_object locking
455 * dt_object locks should be taken inside transaction.
456 * 4. Transaction & RPC
457 * No RPC request should be issued inside transaction.
460 /* the dt device on which the transactions are executed */
461 struct dt_device *th_dev;
463 /* context for this transaction, tag is LCT_TX_HANDLE */
464 struct lu_context th_ctx;
466 /* the last operation result in this transaction.
467 * this value is used in recovery */
472 * Transaction call-backs.
474 * These are invoked by osd (or underlying transaction engine) when
475 * transaction changes state.
477 * Call-backs are used by upper layers to modify transaction parameters and to
478 * perform some actions on for each transaction state transition. Typical
479 * example is mdt registering call-back to write into last-received file
480 * before each transaction commit.
482 struct dt_txn_callback {
483 int (*dtc_txn_start)(const struct lu_env *env,
484 struct txn_param *param, void *cookie);
485 int (*dtc_txn_stop)(const struct lu_env *env,
486 struct thandle *txn, void *cookie);
487 int (*dtc_txn_commit)(const struct lu_env *env,
488 struct thandle *txn, void *cookie);
490 struct list_head dtc_linkage;
493 void dt_txn_callback_add(struct dt_device *dev, struct dt_txn_callback *cb);
494 void dt_txn_callback_del(struct dt_device *dev, struct dt_txn_callback *cb);
496 int dt_txn_hook_start(const struct lu_env *env,
497 struct dt_device *dev, struct txn_param *param);
498 int dt_txn_hook_stop(const struct lu_env *env, struct thandle *txn);
499 int dt_txn_hook_commit(const struct lu_env *env, struct thandle *txn);
501 int dt_try_as_dir(const struct lu_env *env, struct dt_object *obj);
502 struct dt_object *dt_store_open(const struct lu_env *env,
503 struct dt_device *dt, const char *name,
506 #endif /* __LUSTRE_DT_OBJECT_H */