1 /* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
2 * vim:expandtab:shiftwidth=8:tabstop=8:
6 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License version 2 only,
10 * as published by the Free Software Foundation.
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * General Public License version 2 for more details (a copy is included
16 * in the LICENSE file that accompanied this code).
18 * You should have received a copy of the GNU General Public License
19 * version 2 along with this program; If not, see
20 * http://www.sun.com/software/products/lustre/docs/GPLv2.pdf
22 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
23 * CA 95054 USA or visit www.sun.com if you need additional information or
29 * Copyright 2008 Sun Microsystems, Inc. All rights reserved
30 * Use is subject to license terms.
33 * This file is part of Lustre, http://www.lustre.org/
34 * Lustre is a trademark of Sun Microsystems, Inc.
37 #ifndef __LUSTRE_DT_OBJECT_H
38 #define __LUSTRE_DT_OBJECT_H
41 * Sub-class of lu_object with methods common for "data" objects in OST stack.
43 * Data objects behave like regular files: you can read/write them, get and
44 * set their attributes. Implementation of dt interface is supposed to
45 * implement some form of garbage collection, normally reference counting
48 * Examples: osd (lustre/osd) is an implementation of dt interface.
53 * super-class definitions.
55 #include <lu_object.h>
57 #include <libcfs/libcfs.h>
60 struct proc_dir_entry;
67 struct dt_index_features;
69 struct dt_device_param {
70 unsigned ddp_max_name_len;
71 unsigned ddp_max_nlink;
72 unsigned ddp_block_shift;
76 * Basic transaction credit op
86 DTO_LOG_REC, /* XXX temporary: dt layer knows nothing about llog. */
94 * Operations on dt device.
96 struct dt_device_operations {
98 * Return device-wide statistics.
100 int (*dt_statfs)(const struct lu_env *env,
101 struct dt_device *dev, struct kstatfs *sfs);
103 * Start transaction, described by @param.
105 struct thandle *(*dt_trans_start)(const struct lu_env *env,
106 struct dt_device *dev,
107 struct txn_param *param);
109 * Finish previously started transaction.
111 void (*dt_trans_stop)(const struct lu_env *env,
114 * Return fid of root index object.
116 int (*dt_root_get)(const struct lu_env *env,
117 struct dt_device *dev, struct lu_fid *f);
119 * Return device configuration data.
121 void (*dt_conf_get)(const struct lu_env *env,
122 const struct dt_device *dev,
123 struct dt_device_param *param);
125 * handling device state, mostly for tests
127 int (*dt_sync)(const struct lu_env *env, struct dt_device *dev);
128 void (*dt_ro)(const struct lu_env *env, struct dt_device *dev);
130 * Initialize capability context.
132 int (*dt_init_capa_ctxt)(const struct lu_env *env,
133 struct dt_device *dev,
134 int mode, unsigned long timeout,
135 __u32 alg, struct lustre_capa_key *keys);
138 * get transaction credits for given @op.
140 int (*dt_credit_get)(const struct lu_env *env, struct dt_device *dev,
144 struct dt_index_features {
145 /* required feature flags from enum dt_index_flags */
147 /* minimal required key size */
148 size_t dif_keysize_min;
149 /* maximal required key size, 0 if no limit */
150 size_t dif_keysize_max;
151 /* minimal required record size */
152 size_t dif_recsize_min;
153 /* maximal required record size, 0 if no limit */
154 size_t dif_recsize_max;
157 enum dt_index_flags {
158 /* index supports variable sized keys */
159 DT_IND_VARKEY = 1 << 0,
160 /* index supports variable sized records */
161 DT_IND_VARREC = 1 << 1,
162 /* index can be modified */
163 DT_IND_UPDATE = 1 << 2,
164 /* index supports records with non-unique (duplicate) keys */
165 DT_IND_NONUNQ = 1 << 3
169 * Features, required from index to support file system directories (mapping
172 extern const struct dt_index_features dt_directory_features;
175 * This is a general purpose dt allocation hint.
176 * It now contains the parent object.
177 * It can contain any allocation hint in the future.
179 struct dt_allocation_hint {
180 struct dt_object *dah_parent;
185 * Per-dt-object operations.
187 struct dt_object_operations {
188 void (*do_read_lock)(const struct lu_env *env,
189 struct dt_object *dt);
190 void (*do_write_lock)(const struct lu_env *env,
191 struct dt_object *dt);
192 void (*do_read_unlock)(const struct lu_env *env,
193 struct dt_object *dt);
194 void (*do_write_unlock)(const struct lu_env *env,
195 struct dt_object *dt);
197 * Note: following ->do_{x,}attr_{set,get}() operations are very
198 * similar to ->moo_{x,}attr_{set,get}() operations in struct
199 * md_object_operations (see md_object.h). These operations are not in
200 * lu_object_operations, because ->do_{x,}attr_set() versions take
201 * transaction handle as an argument (this transaction is started by
202 * caller). We might factor ->do_{x,}attr_get() into
203 * lu_object_operations, but that would break existing symmetry.
207 * Return standard attributes.
209 * precondition: lu_object_exists(&dt->do_lu);
211 int (*do_attr_get)(const struct lu_env *env,
212 struct dt_object *dt, struct lu_attr *attr,
213 struct lustre_capa *capa);
215 * Set standard attributes.
217 * precondition: dt_object_exists(dt);
219 int (*do_attr_set)(const struct lu_env *env,
220 struct dt_object *dt,
221 const struct lu_attr *attr,
222 struct thandle *handle,
223 struct lustre_capa *capa);
225 * Return a value of an extended attribute.
227 * precondition: dt_object_exists(dt);
229 int (*do_xattr_get)(const struct lu_env *env, struct dt_object *dt,
230 struct lu_buf *buf, const char *name,
231 struct lustre_capa *capa);
233 * Set value of an extended attribute.
235 * @fl - flags from enum lu_xattr_flags
237 * precondition: dt_object_exists(dt);
239 int (*do_xattr_set)(const struct lu_env *env,
240 struct dt_object *dt, const struct lu_buf *buf,
241 const char *name, int fl, struct thandle *handle,
242 struct lustre_capa *capa);
244 * Delete existing extended attribute.
246 * precondition: dt_object_exists(dt);
248 int (*do_xattr_del)(const struct lu_env *env,
249 struct dt_object *dt,
250 const char *name, struct thandle *handle,
251 struct lustre_capa *capa);
253 * Place list of existing extended attributes into @buf (which has
256 * precondition: dt_object_exists(dt);
258 int (*do_xattr_list)(const struct lu_env *env,
259 struct dt_object *dt, struct lu_buf *buf,
260 struct lustre_capa *capa);
262 * Init allocation hint using parent object and child mode.
263 * (1) The @parent might be NULL if this is a partial creation for
265 * (2) The type of child is in @child_mode.
266 * (3) The result hint is stored in @ah;
268 void (*do_ah_init)(const struct lu_env *env,
269 struct dt_allocation_hint *ah,
270 struct dt_object *parent,
273 * Create new object on this device.
275 * precondition: !dt_object_exists(dt);
276 * postcondition: ergo(result == 0, dt_object_exists(dt));
278 int (*do_create)(const struct lu_env *env, struct dt_object *dt,
279 struct lu_attr *attr,
280 struct dt_allocation_hint *hint,
284 * Announce that this object is going to be used as an index. This
285 * operation check that object supports indexing operations and
286 * installs appropriate dt_index_operations vector on success.
288 * Also probes for features. Operation is successful if all required
289 * features are supported.
291 int (*do_index_try)(const struct lu_env *env,
292 struct dt_object *dt,
293 const struct dt_index_features *feat);
295 * Add nlink of the object
296 * precondition: dt_object_exists(dt);
298 void (*do_ref_add)(const struct lu_env *env,
299 struct dt_object *dt, struct thandle *th);
301 * Del nlink of the object
302 * precondition: dt_object_exists(dt);
304 void (*do_ref_del)(const struct lu_env *env,
305 struct dt_object *dt, struct thandle *th);
307 struct obd_capa *(*do_capa_get)(const struct lu_env *env,
308 struct dt_object *dt,
309 struct lustre_capa *old,
311 int (*do_object_sync)(const struct lu_env *, struct dt_object *);
315 * Per-dt-object operations on "file body".
317 struct dt_body_operations {
319 * precondition: dt_object_exists(dt);
321 ssize_t (*dbo_read)(const struct lu_env *env, struct dt_object *dt,
322 struct lu_buf *buf, loff_t *pos,
323 struct lustre_capa *capa);
325 * precondition: dt_object_exists(dt);
327 ssize_t (*dbo_write)(const struct lu_env *env, struct dt_object *dt,
328 const struct lu_buf *buf, loff_t *pos,
329 struct thandle *handle, struct lustre_capa *capa);
333 * Incomplete type of index record.
338 * Incomplete type of index key.
343 * Incomplete type of dt iterator.
348 * Per-dt-object operations on object as index.
350 struct dt_index_operations {
352 * precondition: dt_object_exists(dt);
354 int (*dio_lookup)(const struct lu_env *env, struct dt_object *dt,
355 struct dt_rec *rec, const struct dt_key *key,
356 struct lustre_capa *capa);
358 * precondition: dt_object_exists(dt);
360 int (*dio_insert)(const struct lu_env *env, struct dt_object *dt,
361 const struct dt_rec *rec, const struct dt_key *key,
362 struct thandle *handle, struct lustre_capa *capa);
364 * precondition: dt_object_exists(dt);
366 int (*dio_delete)(const struct lu_env *env, struct dt_object *dt,
367 const struct dt_key *key, struct thandle *handle,
368 struct lustre_capa *capa);
374 * Allocate and initialize new iterator.
376 * precondition: dt_object_exists(dt);
378 struct dt_it *(*init)(const struct lu_env *env,
379 struct dt_object *dt, int writable,
380 struct lustre_capa *capa);
381 void (*fini)(const struct lu_env *env,
383 int (*get)(const struct lu_env *env,
385 const struct dt_key *key);
386 void (*put)(const struct lu_env *env,
388 int (*del)(const struct lu_env *env,
389 struct dt_it *di, struct thandle *th);
390 int (*next)(const struct lu_env *env,
392 struct dt_key *(*key)(const struct lu_env *env,
393 const struct dt_it *di);
394 int (*key_size)(const struct lu_env *env,
395 const struct dt_it *di);
396 struct dt_rec *(*rec)(const struct lu_env *env,
397 const struct dt_it *di);
398 __u64 (*store)(const struct lu_env *env,
399 const struct dt_it *di);
400 int (*load)(const struct lu_env *env,
401 const struct dt_it *di, __u64 hash);
406 struct lu_device dd_lu_dev;
407 struct dt_device_operations *dd_ops;
410 * List of dt_txn_callback (see below). This is not protected in any
411 * way, because callbacks are supposed to be added/deleted only during
412 * single-threaded start-up shut-down procedures.
414 struct list_head dd_txn_callbacks;
417 int dt_device_init(struct dt_device *dev, struct lu_device_type *t);
418 void dt_device_fini(struct dt_device *dev);
420 static inline int lu_device_is_dt(const struct lu_device *d)
422 return ergo(d != NULL, d->ld_type->ldt_tags & LU_DEVICE_DT);
425 static inline struct dt_device * lu2dt_dev(struct lu_device *l)
427 LASSERT(lu_device_is_dt(l));
428 return container_of0(l, struct dt_device, dd_lu_dev);
432 struct lu_object do_lu;
433 struct dt_object_operations *do_ops;
434 struct dt_body_operations *do_body_ops;
435 struct dt_index_operations *do_index_ops;
438 int dt_object_init(struct dt_object *obj,
439 struct lu_object_header *h, struct lu_device *d);
441 void dt_object_fini(struct dt_object *obj);
443 static inline int dt_object_exists(const struct dt_object *dt)
445 return lu_object_exists(&dt->do_lu);
449 /* number of blocks this transaction will modify */
450 unsigned int tp_credits;
451 /* sync transaction is needed */
455 static inline void txn_param_init(struct txn_param *p, unsigned int credits)
457 memset(p, 0, sizeof(*p));
458 p->tp_credits = credits;
462 * This is the general purpose transaction handle.
463 * 1. Transaction Life Cycle
464 * This transaction handle is allocated upon starting a new transaction,
465 * and deallocated after this transaction is committed.
466 * 2. Transaction Nesting
467 * We do _NOT_ support nested transaction. So, every thread should only
468 * have one active transaction, and a transaction only belongs to one
469 * thread. Due to this, transaction handle need no reference count.
470 * 3. Transaction & dt_object locking
471 * dt_object locks should be taken inside transaction.
472 * 4. Transaction & RPC
473 * No RPC request should be issued inside transaction.
476 /* the dt device on which the transactions are executed */
477 struct dt_device *th_dev;
479 /* context for this transaction, tag is LCT_TX_HANDLE */
480 struct lu_context th_ctx;
482 /* the last operation result in this transaction.
483 * this value is used in recovery */
488 * Transaction call-backs.
490 * These are invoked by osd (or underlying transaction engine) when
491 * transaction changes state.
493 * Call-backs are used by upper layers to modify transaction parameters and to
494 * perform some actions on for each transaction state transition. Typical
495 * example is mdt registering call-back to write into last-received file
496 * before each transaction commit.
498 struct dt_txn_callback {
499 int (*dtc_txn_start)(const struct lu_env *env,
500 struct txn_param *param, void *cookie);
501 int (*dtc_txn_stop)(const struct lu_env *env,
502 struct thandle *txn, void *cookie);
503 int (*dtc_txn_commit)(const struct lu_env *env,
504 struct thandle *txn, void *cookie);
506 struct list_head dtc_linkage;
509 void dt_txn_callback_add(struct dt_device *dev, struct dt_txn_callback *cb);
510 void dt_txn_callback_del(struct dt_device *dev, struct dt_txn_callback *cb);
512 int dt_txn_hook_start(const struct lu_env *env,
513 struct dt_device *dev, struct txn_param *param);
514 int dt_txn_hook_stop(const struct lu_env *env, struct thandle *txn);
515 int dt_txn_hook_commit(const struct lu_env *env, struct thandle *txn);
517 int dt_try_as_dir(const struct lu_env *env, struct dt_object *obj);
518 struct dt_object *dt_store_open(const struct lu_env *env,
519 struct dt_device *dt, const char *name,
522 #endif /* __LUSTRE_DT_OBJECT_H */