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  *  Copyright (C) 2006 Cluster File Systems, Inc.
   5  *
   6  *   This file is part of Lustre, http://www.lustre.org.
   7  *
   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.
  11  *
  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.
  16  *
  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.
  20  *
  21  */
  22
  23 #ifndef __LUSTRE_DT_OBJECT_H
  24 #define __LUSTRE_DT_OBJECT_H
  25
  26 /*
  27  * Sub-class of lu_object with methods common for "data" objects in OST stack.
  28  *
  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
  32  * (nlink) based one.
  33  *
  34  * Examples: osd (lustre/osd) is an implementation of dt interface.
  35  */
  36
  37
  38 /*
  39  * super-class definitions.
  40  */
  41 #include <lu_object.h>
  42
  43 #include <libcfs/list.h>
  44 #include <libcfs/kp30.h>
  45
  46 struct seq_file;
  47 struct proc_dir_entry;
  48 struct lustre_cfg;
  49
  50 struct thandle;
  51 struct txn_param;
  52 struct dt_device;
  53 struct dt_object;
  54 struct dt_index_features;
  55
  56 struct dt_device_param {
  57         unsigned           ddp_max_name_len;
  58         unsigned           ddp_max_nlink;
  59         unsigned           ddp_block_shift;
  60 };
  61
  62 /*
  63  * Basic transaction credit op
  64  */
  65 enum dt_txn_op {
  66         DTO_INDEX_INSERT,
  67         DTO_INDEX_DELETE,
  68         DTO_IDNEX_UPDATE,
  69         DTO_OBJECT_CREATE,
  70         DTO_OBJECT_DELETE,
  71         DTO_ATTR_SET,
  72         DTO_XATTR_SET,
  73         DTO_LOG_REC, /* XXX temporary: dt layer knows nothing about llog. */
  74
  75         DTO_NR
  76 };
  77
  78 /*
  79  * Operations on dt device.
  80  */
  81 struct dt_device_operations {
  82         /*
  83          * Return device-wide statistics.
  84          */
  85         int   (*dt_statfs)(const struct lu_env *env,
  86                            struct dt_device *dev, struct kstatfs *sfs);
  87         /*
  88          * Start transaction, described by @param.
  89          */
  90         struct thandle *(*dt_trans_start)(const struct lu_env *env,
  91                                           struct dt_device *dev,
  92                                           struct txn_param *param);
  93         /*
  94          * Finish previously started transaction.
  95          */
  96         void  (*dt_trans_stop)(const struct lu_env *env,
  97                                struct thandle *th);
  98         /*
  99          * Return fid of root index object.
 100          */
 101         int   (*dt_root_get)(const struct lu_env *env,
 102                              struct dt_device *dev, struct lu_fid *f);
 103         /*
 104          * Return device configuration data.
 105          */
 106         void  (*dt_conf_get)(const struct lu_env *env,
 107                              const struct dt_device *dev,
 108                              struct dt_device_param *param);
 109         /*
 110          *  handling device state, mostly for tests
 111          */
 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);
 114         /*
 115          * Initialize capability context.
 116          */
 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);
 121
 122         /*
 123          *  get transaction credits for given @op.
 124          */
 125         int (*dt_credit_get)(const struct lu_env *env, struct dt_device *dev,
 126                              enum dt_txn_op);
 127 };
 128
 129 struct dt_index_features {
 130         /* required feature flags from enum dt_index_flags */
 131         __u32 dif_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;
 140 };
 141
 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
 151 };
 152
 153 /*
 154  * Features, required from index to support file system directories (mapping
 155  * names to fids).
 156  */
 157 extern const struct dt_index_features dt_directory_features;
 158
 159 /*
 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.
 163  */
 164 struct dt_allocation_hint {
 165         struct dt_object *dah_parent;
 166         __u32             dah_mode;
 167 };
 168
 169 /*
 170  * Per-dt-object operations.
 171  */
 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);
 181         /*
 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.
 189          */
 190
 191         /*
 192          * Return standard attributes.
 193          *
 194          * precondition: lu_object_exists(&dt->do_lu);
 195          */
 196         int   (*do_attr_get)(const struct lu_env *env,
 197                              struct dt_object *dt, struct lu_attr *attr,
 198                              struct lustre_capa *capa);
 199         /*
 200          * Set standard attributes.
 201          *
 202          * precondition: dt_object_exists(dt);
 203          */
 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);
 209         /*
 210          * Return a value of an extended attribute.
 211          *
 212          * precondition: dt_object_exists(dt);
 213          */
 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);
 217         /*
 218          * Set value of an extended attribute.
 219          *
 220          * @fl - flags from enum lu_xattr_flags
 221          *
 222          * precondition: dt_object_exists(dt);
 223          */
 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);
 228         /*
 229          * Delete existing extended attribute.
 230          *
 231          * precondition: dt_object_exists(dt);
 232          */
 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);
 237         /*
 238          * Place list of existing extended attributes into @buf (which has
 239          * length len).
 240          *
 241          * precondition: dt_object_exists(dt);
 242          */
 243         int   (*do_xattr_list)(const struct lu_env *env,
 244                                struct dt_object *dt, struct lu_buf *buf,
 245                                struct lustre_capa *capa);
 246         /*
 247          * Init allocation hint using parent object and child mode.
 248          * (1) The @parent might be NULL if this is a partial creation for
 249          *     remote object.
 250          * (2) The type of child is in @child_mode.
 251          * (3) The result hint is stored in @ah;
 252          */
 253         void  (*do_ah_init)(const struct lu_env *env,
 254                             struct dt_allocation_hint *ah,
 255                             struct dt_object *parent,
 256                             umode_t child_mode);
 257         /*
 258          * Create new object on this device.
 259          *
 260          * precondition: !dt_object_exists(dt);
 261          * postcondition: ergo(result == 0, dt_object_exists(dt));
 262          */
 263         int   (*do_create)(const struct lu_env *env, struct dt_object *dt,
 264                            struct lu_attr *attr,
 265                            struct dt_allocation_hint *hint,
 266                            struct thandle *th);
 267
 268         /*
 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.
 272          *
 273          * Also probes for features. Operation is successful if all required
 274          * features are supported.
 275          */
 276         int   (*do_index_try)(const struct lu_env *env,
 277                               struct dt_object *dt,
 278                               const struct dt_index_features *feat);
 279         /*
 280          * Add nlink of the object
 281          * precondition: dt_object_exists(dt);
 282          */
 283         void  (*do_ref_add)(const struct lu_env *env,
 284                             struct dt_object *dt, struct thandle *th);
 285         /*
 286          * Del nlink of the object
 287          * precondition: dt_object_exists(dt);
 288          */
 289         void  (*do_ref_del)(const struct lu_env *env,
 290                             struct dt_object *dt, struct thandle *th);
 291
 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);
 296 };
 297
 298 /*
 299  * Per-dt-object operations on "file body".
 300  */
 301 struct dt_body_operations {
 302         /*
 303          * precondition: dt_object_exists(dt);
 304          */
 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);
 308         /*
 309          * precondition: dt_object_exists(dt);
 310          */
 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);
 314 };
 315
 316 /*
 317  * Incomplete type of index record.
 318  */
 319 struct dt_rec;
 320
 321 /*
 322  * Incomplete type of index key.
 323  */
 324 struct dt_key;
 325
 326 /*
 327  * Incomplete type of dt iterator.
 328  */
 329 struct dt_it;
 330
 331 /*
 332  * Per-dt-object operations on object as index.
 333  */
 334 struct dt_index_operations {
 335         /*
 336          * precondition: dt_object_exists(dt);
 337          */
 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);
 341         /*
 342          * precondition: dt_object_exists(dt);
 343          */
 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);
 347         /*
 348          * precondition: dt_object_exists(dt);
 349          */
 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);
 353         /*
 354          * Iterator interface
 355          */
 356         struct dt_it_ops {
 357                 /*
 358                  * Allocate and initialize new iterator.
 359                  *
 360                  * precondition: dt_object_exists(dt);
 361                  */
 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,
 366                                       struct dt_it *di);
 367                 int            (*get)(const struct lu_env *env,
 368                                       struct dt_it *di,
 369                                       const struct dt_key *key);
 370                 void           (*put)(const struct lu_env *env,
 371                                       struct dt_it *di);
 372                 int            (*del)(const struct lu_env *env,
 373                                       struct dt_it *di, struct thandle *th);
 374                 int           (*next)(const struct lu_env *env,
 375                                       struct dt_it *di);
 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);
 386         } dio_it;
 387 };
 388
 389 struct dt_device {
 390         struct lu_device             dd_lu_dev;
 391         struct dt_device_operations *dd_ops;
 392
 393         /*
 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.
 397          */
 398         struct list_head             dd_txn_callbacks;
 399 };
 400
 401 int  dt_device_init(struct dt_device *dev, struct lu_device_type *t);
 402 void dt_device_fini(struct dt_device *dev);
 403
 404 static inline int lu_device_is_dt(const struct lu_device *d)
 405 {
 406         return ergo(d != NULL, d->ld_type->ldt_tags & LU_DEVICE_DT);
 407 }
 408
 409 static inline struct dt_device * lu2dt_dev(struct lu_device *l)
 410 {
 411         LASSERT(lu_device_is_dt(l));
 412         return container_of0(l, struct dt_device, dd_lu_dev);
 413 }
 414
 415 struct dt_object {
 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;
 420 };
 421
 422 int  dt_object_init(struct dt_object *obj,
 423                     struct lu_object_header *h, struct lu_device *d);
 424
 425 void dt_object_fini(struct dt_object *obj);
 426
 427 static inline int dt_object_exists(const struct dt_object *dt)
 428 {
 429         return lu_object_exists(&dt->do_lu);
 430 }
 431
 432 struct txn_param {
 433         /* number of blocks this transaction will modify */
 434         unsigned int tp_credits;
 435         /* sync transaction is needed */
 436         __u32        tp_sync:1;
 437 };
 438
 439 static inline void txn_param_init(struct txn_param *p, unsigned int credits)
 440 {
 441         memset(p, 0, sizeof(*p));
 442         p->tp_credits = credits;
 443 }
 444
 445 /*
 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.
 458  */
 459 struct thandle {
 460         /* the dt device on which the transactions are executed */
 461         struct dt_device *th_dev;
 462
 463         /* context for this transaction, tag is LCT_TX_HANDLE */
 464         struct lu_context th_ctx;
 465
 466         /* the last operation result in this transaction.
 467          * this value is used in recovery */
 468         __s32             th_result;
 469 };
 470
 471 /*
 472  * Transaction call-backs.
 473  *
 474  * These are invoked by osd (or underlying transaction engine) when
 475  * transaction changes state.
 476  *
 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.
 481  */
 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);
 489         void            *dtc_cookie;
 490         struct list_head dtc_linkage;
 491 };
 492
 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);
 495
 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);
 500
 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,
 504                                 struct lu_fid *fid);
 505
 506 #endif /* __LUSTRE_DT_OBJECT_H */