lustre/include/dt_object.h

   1 /* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
   2  * vim:expandtab:shiftwidth=8:tabstop=8:
   3  *
   4  * GPL HEADER START
   5  *
   6  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   7  *
   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.
  11  *
  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).
  17  *
  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
  21  *
  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
  24  * have any questions.
  25  *
  26  * GPL HEADER END
  27  */
  28 /*
  29  * Copyright  2008 Sun Microsystems, Inc. All rights reserved
  30  * Use is subject to license terms.
  31  */
  32 /*
  33  * This file is part of Lustre, http://www.lustre.org/
  34  * Lustre is a trademark of Sun Microsystems, Inc.
  35  */
  36
  37 #ifndef __LUSTRE_DT_OBJECT_H
  38 #define __LUSTRE_DT_OBJECT_H
  39
  40 /** \defgroup dt dt
  41  * Sub-class of lu_object with methods common for "data" objects in OST stack.
  42  *
  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
  46  * (nlink) based one.
  47  *
  48  * Examples: osd (lustre/osd) is an implementation of dt interface.
  49  * @{
  50  */
  51
  52
  53 /*
  54  * super-class definitions.
  55  */
  56 #include <lu_object.h>
  57
  58 #include <libcfs/libcfs.h>
  59
  60 struct seq_file;
  61 struct proc_dir_entry;
  62 struct lustre_cfg;
  63
  64 struct thandle;
  65 struct txn_param;
  66 struct dt_device;
  67 struct dt_object;
  68 struct dt_index_features;
  69
  70 struct dt_device_param {
  71         unsigned           ddp_max_name_len;
  72         unsigned           ddp_max_nlink;
  73         unsigned           ddp_block_shift;
  74 };
  75
  76 /**
  77  * Basic transaction credit op
  78  */
  79 enum dt_txn_op {
  80         DTO_INDEX_INSERT,
  81         DTO_INDEX_DELETE,
  82         DTO_IDNEX_UPDATE,
  83         DTO_OBJECT_CREATE,
  84         DTO_OBJECT_DELETE,
  85         DTO_ATTR_SET,
  86         DTO_XATTR_SET,
  87         DTO_LOG_REC, /**< XXX temporary: dt layer knows nothing about llog. */
  88         DTO_WRITE_BASE,
  89         DTO_WRITE_BLOCK,
  90
  91         DTO_NR
  92 };
  93
  94 /**
  95  * Operations on dt device.
  96  */
  97 struct dt_device_operations {
  98         /**
  99          * Return device-wide statistics.
 100          */
 101         int   (*dt_statfs)(const struct lu_env *env,
 102                            struct dt_device *dev, struct kstatfs *sfs);
 103         /**
 104          * Start transaction, described by \a param.
 105          */
 106         struct thandle *(*dt_trans_start)(const struct lu_env *env,
 107                                           struct dt_device *dev,
 108                                           struct txn_param *param);
 109         /**
 110          * Finish previously started transaction.
 111          */
 112         void  (*dt_trans_stop)(const struct lu_env *env,
 113                                struct thandle *th);
 114         /**
 115          * Return fid of root index object.
 116          */
 117         int   (*dt_root_get)(const struct lu_env *env,
 118                              struct dt_device *dev, struct lu_fid *f);
 119         /**
 120          * Return device configuration data.
 121          */
 122         void  (*dt_conf_get)(const struct lu_env *env,
 123                              const struct dt_device *dev,
 124                              struct dt_device_param *param);
 125         /**
 126          *  handling device state, mostly for tests
 127          */
 128         int   (*dt_sync)(const struct lu_env *env, struct dt_device *dev);
 129         void  (*dt_ro)(const struct lu_env *env, struct dt_device *dev);
 130         /**
 131          * Initialize capability context.
 132          */
 133         int   (*dt_init_capa_ctxt)(const struct lu_env *env,
 134                                    struct dt_device *dev,
 135                                    int mode, unsigned long timeout,
 136                                    __u32 alg, struct lustre_capa_key *keys);
 137
 138         /**
 139          *  get transaction credits for given \a op.
 140          */
 141         int (*dt_credit_get)(const struct lu_env *env, struct dt_device *dev,
 142                              enum dt_txn_op);
 143 };
 144
 145 struct dt_index_features {
 146         /** required feature flags from enum dt_index_flags */
 147         __u32 dif_flags;
 148         /** minimal required key size */
 149         size_t dif_keysize_min;
 150         /** maximal required key size, 0 if no limit */
 151         size_t dif_keysize_max;
 152         /** minimal required record size */
 153         size_t dif_recsize_min;
 154         /** maximal required record size, 0 if no limit */
 155         size_t dif_recsize_max;
 156 };
 157
 158 enum dt_index_flags {
 159         /** index supports variable sized keys */
 160         DT_IND_VARKEY = 1 << 0,
 161         /** index supports variable sized records */
 162         DT_IND_VARREC = 1 << 1,
 163         /** index can be modified */
 164         DT_IND_UPDATE = 1 << 2,
 165         /** index supports records with non-unique (duplicate) keys */
 166         DT_IND_NONUNQ = 1 << 3
 167 };
 168
 169 /**
 170  * Features, required from index to support file system directories (mapping
 171  * names to fids).
 172  */
 173 extern const struct dt_index_features dt_directory_features;
 174
 175 /**
 176  * This is a general purpose dt allocation hint.
 177  * It now contains the parent object.
 178  * It can contain any allocation hint in the future.
 179  */
 180 struct dt_allocation_hint {
 181         struct dt_object *dah_parent;
 182         __u32             dah_mode;
 183 };
 184
 185 /**
 186  * Per-dt-object operations.
 187  */
 188 struct dt_object_operations {
 189         void  (*do_read_lock)(const struct lu_env *env,
 190                               struct dt_object *dt, unsigned role);
 191         void  (*do_write_lock)(const struct lu_env *env,
 192                                struct dt_object *dt, unsigned role);
 193         void  (*do_read_unlock)(const struct lu_env *env,
 194                                 struct dt_object *dt);
 195         void  (*do_write_unlock)(const struct lu_env *env,
 196                                  struct dt_object *dt);
 197         /**
 198          * Note: following ->do_{x,}attr_{set,get}() operations are very
 199          * similar to ->moo_{x,}attr_{set,get}() operations in struct
 200          * md_object_operations (see md_object.h). These operations are not in
 201          * lu_object_operations, because ->do_{x,}attr_set() versions take
 202          * transaction handle as an argument (this transaction is started by
 203          * caller). We might factor ->do_{x,}attr_get() into
 204          * lu_object_operations, but that would break existing symmetry.
 205          */
 206
 207         /**
 208          * Return standard attributes.
 209          *
 210          * precondition: lu_object_exists(&dt->do_lu);
 211          */
 212         int   (*do_attr_get)(const struct lu_env *env,
 213                              struct dt_object *dt, struct lu_attr *attr,
 214                              struct lustre_capa *capa);
 215         /**
 216          * Set standard attributes.
 217          *
 218          * precondition: dt_object_exists(dt);
 219          */
 220         int   (*do_attr_set)(const struct lu_env *env,
 221                              struct dt_object *dt,
 222                              const struct lu_attr *attr,
 223                              struct thandle *handle,
 224                              struct lustre_capa *capa);
 225         /**
 226          * Return a value of an extended attribute.
 227          *
 228          * precondition: dt_object_exists(dt);
 229          */
 230         int   (*do_xattr_get)(const struct lu_env *env, struct dt_object *dt,
 231                               struct lu_buf *buf, const char *name,
 232                               struct lustre_capa *capa);
 233         /**
 234          * Set value of an extended attribute.
 235          *
 236          * \a fl - flags from enum lu_xattr_flags
 237          *
 238          * precondition: dt_object_exists(dt);
 239          */
 240         int   (*do_xattr_set)(const struct lu_env *env,
 241                               struct dt_object *dt, const struct lu_buf *buf,
 242                               const char *name, int fl, struct thandle *handle,
 243                               struct lustre_capa *capa);
 244         /**
 245          * Delete existing extended attribute.
 246          *
 247          * precondition: dt_object_exists(dt);
 248          */
 249         int   (*do_xattr_del)(const struct lu_env *env,
 250                               struct dt_object *dt,
 251                               const char *name, struct thandle *handle,
 252                               struct lustre_capa *capa);
 253         /**
 254          * Place list of existing extended attributes into \a buf (which has
 255          * length len).
 256          *
 257          * precondition: dt_object_exists(dt);
 258          */
 259         int   (*do_xattr_list)(const struct lu_env *env,
 260                                struct dt_object *dt, struct lu_buf *buf,
 261                                struct lustre_capa *capa);
 262         /**
 263          * Init allocation hint using parent object and child mode.
 264          * (1) The \a parent might be NULL if this is a partial creation for
 265          *     remote object.
 266          * (2) The type of child is in \a child_mode.
 267          * (3) The result hint is stored in \a ah;
 268          */
 269         void  (*do_ah_init)(const struct lu_env *env,
 270                             struct dt_allocation_hint *ah,
 271                             struct dt_object *parent,
 272                             umode_t child_mode);
 273         /**
 274          * Create new object on this device.
 275          *
 276          * precondition: !dt_object_exists(dt);
 277          * postcondition: ergo(result == 0, dt_object_exists(dt));
 278          */
 279         int   (*do_create)(const struct lu_env *env, struct dt_object *dt,
 280                            struct lu_attr *attr,
 281                            struct dt_allocation_hint *hint,
 282                            struct thandle *th);
 283
 284         /**
 285          * Announce that this object is going to be used as an index. This
 286          * operation check that object supports indexing operations and
 287          * installs appropriate dt_index_operations vector on success.
 288          *
 289          * Also probes for features. Operation is successful if all required
 290          * features are supported.
 291          */
 292         int   (*do_index_try)(const struct lu_env *env,
 293                               struct dt_object *dt,
 294                               const struct dt_index_features *feat);
 295         /**
 296          * Add nlink of the object
 297          * precondition: dt_object_exists(dt);
 298          */
 299         void  (*do_ref_add)(const struct lu_env *env,
 300                             struct dt_object *dt, struct thandle *th);
 301         /**
 302          * Del nlink of the object
 303          * precondition: dt_object_exists(dt);
 304          */
 305         void  (*do_ref_del)(const struct lu_env *env,
 306                             struct dt_object *dt, struct thandle *th);
 307
 308         struct obd_capa *(*do_capa_get)(const struct lu_env *env,
 309                                         struct dt_object *dt,
 310                                         struct lustre_capa *old,
 311                                         __u64 opc);
 312         int (*do_object_sync)(const struct lu_env *, struct dt_object *);
 313 };
 314
 315 /**
 316  * Per-dt-object operations on "file body".
 317  */
 318 struct dt_body_operations {
 319         /**
 320          * precondition: dt_object_exists(dt);
 321          */
 322         ssize_t (*dbo_read)(const struct lu_env *env, struct dt_object *dt,
 323                             struct lu_buf *buf, loff_t *pos,
 324                             struct lustre_capa *capa);
 325         /**
 326          * precondition: dt_object_exists(dt);
 327          */
 328         ssize_t (*dbo_write)(const struct lu_env *env, struct dt_object *dt,
 329                              const struct lu_buf *buf, loff_t *pos,
 330                              struct thandle *handle, struct lustre_capa *capa);
 331 };
 332
 333 /**
 334  * Incomplete type of index record.
 335  */
 336 struct dt_rec;
 337
 338 /**
 339  * Incomplete type of index key.
 340  */
 341 struct dt_key;
 342
 343 /**
 344  * Incomplete type of dt iterator.
 345  */
 346 struct dt_it;
 347
 348 /**
 349  * Per-dt-object operations on object as index.
 350  */
 351 struct dt_index_operations {
 352         /**
 353          * precondition: dt_object_exists(dt);
 354          */
 355         int (*dio_lookup)(const struct lu_env *env, struct dt_object *dt,
 356                           struct dt_rec *rec, const struct dt_key *key,
 357                           struct lustre_capa *capa);
 358         /**
 359          * precondition: dt_object_exists(dt);
 360          */
 361         int (*dio_insert)(const struct lu_env *env, struct dt_object *dt,
 362                           const struct dt_rec *rec, const struct dt_key *key,
 363                           struct thandle *handle, struct lustre_capa *capa);
 364         /**
 365          * precondition: dt_object_exists(dt);
 366          */
 367         int (*dio_delete)(const struct lu_env *env, struct dt_object *dt,
 368                           const struct dt_key *key, struct thandle *handle,
 369                           struct lustre_capa *capa);
 370         /**
 371          * Iterator interface
 372          */
 373         struct dt_it_ops {
 374                 /**
 375                  * Allocate and initialize new iterator.
 376                  *
 377                  * precondition: dt_object_exists(dt);
 378                  */
 379                 struct dt_it *(*init)(const struct lu_env *env,
 380                                       struct dt_object *dt, int writable,
 381                                       struct lustre_capa *capa);
 382                 void          (*fini)(const struct lu_env *env,
 383                                       struct dt_it *di);
 384                 int            (*get)(const struct lu_env *env,
 385                                       struct dt_it *di,
 386                                       const struct dt_key *key);
 387                 void           (*put)(const struct lu_env *env,
 388                                       struct dt_it *di);
 389                 int            (*del)(const struct lu_env *env,
 390                                       struct dt_it *di, struct thandle *th);
 391                 int           (*next)(const struct lu_env *env,
 392                                       struct dt_it *di);
 393                 struct dt_key *(*key)(const struct lu_env *env,
 394                                       const struct dt_it *di);
 395                 int       (*key_size)(const struct lu_env *env,
 396                                       const struct dt_it *di);
 397                 struct dt_rec *(*rec)(const struct lu_env *env,
 398                                       const struct dt_it *di);
 399                 __u64        (*store)(const struct lu_env *env,
 400                                       const struct dt_it *di);
 401                 int           (*load)(const struct lu_env *env,
 402                                       const struct dt_it *di, __u64 hash);
 403         } dio_it;
 404 };
 405
 406 struct dt_device {
 407         struct lu_device             dd_lu_dev;
 408         const struct dt_device_operations *dd_ops;
 409
 410         /**
 411          * List of dt_txn_callback (see below). This is not protected in any
 412          * way, because callbacks are supposed to be added/deleted only during
 413          * single-threaded start-up shut-down procedures.
 414          */
 415         struct list_head             dd_txn_callbacks;
 416 };
 417
 418 int  dt_device_init(struct dt_device *dev, struct lu_device_type *t);
 419 void dt_device_fini(struct dt_device *dev);
 420
 421 static inline int lu_device_is_dt(const struct lu_device *d)
 422 {
 423         return ergo(d != NULL, d->ld_type->ldt_tags & LU_DEVICE_DT);
 424 }
 425
 426 static inline struct dt_device * lu2dt_dev(struct lu_device *l)
 427 {
 428         LASSERT(lu_device_is_dt(l));
 429         return container_of0(l, struct dt_device, dd_lu_dev);
 430 }
 431
 432 struct dt_object {
 433         struct lu_object             do_lu;
 434         const struct dt_object_operations *do_ops;
 435         const struct dt_body_operations   *do_body_ops;
 436         const struct dt_index_operations  *do_index_ops;
 437 };
 438
 439 int  dt_object_init(struct dt_object *obj,
 440                     struct lu_object_header *h, struct lu_device *d);
 441
 442 void dt_object_fini(struct dt_object *obj);
 443
 444 static inline int dt_object_exists(const struct dt_object *dt)
 445 {
 446         return lu_object_exists(&dt->do_lu);
 447 }
 448
 449 struct txn_param {
 450         /** number of blocks this transaction will modify */
 451         unsigned int tp_credits;
 452         /** sync transaction is needed */
 453         __u32        tp_sync:1;
 454 };
 455
 456 static inline void txn_param_init(struct txn_param *p, unsigned int credits)
 457 {
 458         memset(p, 0, sizeof(*p));
 459         p->tp_credits = credits;
 460 }
 461
 462 /**
 463  * This is the general purpose transaction handle.
 464  * 1. Transaction Life Cycle
 465  *      This transaction handle is allocated upon starting a new transaction,
 466  *      and deallocated after this transaction is committed.
 467  * 2. Transaction Nesting
 468  *      We do _NOT_ support nested transaction. So, every thread should only
 469  *      have one active transaction, and a transaction only belongs to one
 470  *      thread. Due to this, transaction handle need no reference count.
 471  * 3. Transaction & dt_object locking
 472  *      dt_object locks should be taken inside transaction.
 473  * 4. Transaction & RPC
 474  *      No RPC request should be issued inside transaction.
 475  */
 476 struct thandle {
 477         /** the dt device on which the transactions are executed */
 478         struct dt_device *th_dev;
 479
 480         /** context for this transaction, tag is LCT_TX_HANDLE */
 481         struct lu_context th_ctx;
 482
 483         /** the last operation result in this transaction.
 484          * this value is used in recovery */
 485         __s32             th_result;
 486 };
 487
 488 /**
 489  * Transaction call-backs.
 490  *
 491  * These are invoked by osd (or underlying transaction engine) when
 492  * transaction changes state.
 493  *
 494  * Call-backs are used by upper layers to modify transaction parameters and to
 495  * perform some actions on for each transaction state transition. Typical
 496  * example is mdt registering call-back to write into last-received file
 497  * before each transaction commit.
 498  */
 499 struct dt_txn_callback {
 500         int (*dtc_txn_start)(const struct lu_env *env,
 501                              struct txn_param *param, void *cookie);
 502         int (*dtc_txn_stop)(const struct lu_env *env,
 503                             struct thandle *txn, void *cookie);
 504         int (*dtc_txn_commit)(const struct lu_env *env,
 505                               struct thandle *txn, void *cookie);
 506         void            *dtc_cookie;
 507         struct list_head dtc_linkage;
 508 };
 509
 510 void dt_txn_callback_add(struct dt_device *dev, struct dt_txn_callback *cb);
 511 void dt_txn_callback_del(struct dt_device *dev, struct dt_txn_callback *cb);
 512
 513 int dt_txn_hook_start(const struct lu_env *env,
 514                       struct dt_device *dev, struct txn_param *param);
 515 int dt_txn_hook_stop(const struct lu_env *env, struct thandle *txn);
 516 int dt_txn_hook_commit(const struct lu_env *env, struct thandle *txn);
 517
 518 int dt_try_as_dir(const struct lu_env *env, struct dt_object *obj);
 519 struct dt_object *dt_store_open(const struct lu_env *env,
 520                                 struct dt_device *dt, const char *name,
 521                                 struct lu_fid *fid);
 522
 523 /** @} dt */
 524
 525 #endif /* __LUSTRE_DT_OBJECT_H */