- /**
- * precondition: dt_object_exists(dt);
- */
- ssize_t (*dbo_read)(const struct lu_env *env, struct dt_object *dt,
- struct lu_buf *buf, loff_t *pos,
- struct lustre_capa *capa);
- /**
- * precondition: dt_object_exists(dt);
- */
- ssize_t (*dbo_declare_write)(const struct lu_env *env,
- struct dt_object *dt,
- const loff_t size, loff_t pos,
- struct thandle *handle);
- ssize_t (*dbo_write)(const struct lu_env *env, struct dt_object *dt,
- const struct lu_buf *buf, loff_t *pos,
- struct thandle *handle, struct lustre_capa *capa,
- int ignore_quota);
- /*
- * methods for zero-copy IO
- */
-
- /*
- * precondition: dt_object_exists(dt);
- * returns:
- * < 0 - error code
- * = 0 - illegal
- * > 0 - number of local buffers prepared
- */
- int (*dbo_bufs_get)(const struct lu_env *env, struct dt_object *dt,
- loff_t pos, ssize_t len, struct niobuf_local *lb,
- int rw, struct lustre_capa *capa);
- /*
- * precondition: dt_object_exists(dt);
- */
- int (*dbo_bufs_put)(const struct lu_env *env, struct dt_object *dt,
- struct niobuf_local *lb, int nr);
- /*
- * precondition: dt_object_exists(dt);
- */
- int (*dbo_write_prep)(const struct lu_env *env, struct dt_object *dt,
- struct niobuf_local *lb, int nr);
- /*
- * precondition: dt_object_exists(dt);
- */
- int (*dbo_declare_write_commit)(const struct lu_env *env,
- struct dt_object *dt,
- struct niobuf_local *,
- int, struct thandle *);
- /*
- * precondition: dt_object_exists(dt);
- */
- int (*dbo_write_commit)(const struct lu_env *env, struct dt_object *dt,
- struct niobuf_local *, int, struct thandle *);
- /*
- * precondition: dt_object_exists(dt);
- */
- int (*dbo_read_prep)(const struct lu_env *env, struct dt_object *dt,
- struct niobuf_local *lnb, int nr);
- int (*dbo_fiemap_get)(const struct lu_env *env, struct dt_object *dt,
- struct ll_user_fiemap *fm);
- /**
- * Punch object's content
- * precondition: regular object, not index
- */
- int (*do_declare_punch)(const struct lu_env *, struct dt_object *,
- __u64, __u64, struct thandle *th);
- int (*do_punch)(const struct lu_env *env, struct dt_object *dt,
- __u64 start, __u64 end, struct thandle *th,
- struct lustre_capa *capa);
+ /**
+ * Read data.
+ *
+ * Read unstructured data from an existing regular object.
+ * Only data before attr.la_size is returned.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[out] buf buffer (including size) to copy data in
+ * \param[in] pos position in the object to start
+ * \param[out] pos original value of \a pos + bytes returned
+ *
+ * \retval positive bytes read on success
+ * \retval negative negated errno on error
+ */
+ ssize_t (*dbo_read)(const struct lu_env *env,
+ struct dt_object *dt,
+ struct lu_buf *buf,
+ loff_t *pos);
+
+ /**
+ * Declare intention to write data to object.
+ *
+ * Notify the underlying filesystem that data may be written in
+ * this transaction. This enables the layer below to prepare resources
+ * (e.g. journal credits in ext4). This method should be called
+ * between creating the transaction and starting it. The object need
+ * not exist. If the layer implementing this method is responsible for
+ * quota, then the method should reserve space for the given credentials
+ * and return an error if quota is over. If the write later fails
+ * for some reason, then the reserve should be released properly
+ * (usually in ->dt_trans_stop()).
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] buf buffer (including size) to copy data from
+ * \param[in] pos position in the object to start
+ * \param[in] th transaction handle
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ ssize_t (*dbo_declare_write)(const struct lu_env *env,
+ struct dt_object *dt,
+ const struct lu_buf *buf,
+ loff_t pos,
+ struct thandle *th);
+
+ /**
+ * Write unstructured data to regular existing object.
+ *
+ * The method allocates space and puts data in. Also, the method should
+ * maintain attr.la_size properly. Partial writes are possible.
+ *
+ * If the layer implementing this method is responsible for quota,
+ * then the method should maintain space accounting for the given
+ * credentials.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] buf buffer (including size) to copy data from
+ * \param[in] pos position in the object to start
+ * \param[out] pos \a pos + bytes written
+ * \param[in] th transaction handle
+ *
+ * \retval positive bytes written on success
+ * \retval negative negated errno on error
+ */
+ ssize_t (*dbo_write)(const struct lu_env *env,
+ struct dt_object *dt,
+ const struct lu_buf *buf,
+ loff_t *pos,
+ struct thandle *th);
+
+ /**
+ * Return buffers for data.
+ *
+ * This method is used to access data with no copying. It's so-called
+ * zero-copy I/O. The method returns the descriptors for the internal
+ * buffers where data are managed by the disk filesystem. For example,
+ * pagecache in case of ext4 or ARC with ZFS. Then other components
+ * (e.g. networking) can transfer data from or to the buffers with no
+ * additional copying.
+ *
+ * The method should fill an array of struct niobuf_local, where
+ * each element describes a full or partial page for data at specific
+ * offset. The caller should use page/lnb_page_offset/len to find data
+ * at object's offset lnb_file_offset.
+ *
+ * The memory referenced by the descriptors can't change its purpose
+ * until the complementary ->dbo_bufs_put() is called. The caller should
+ * specify if the buffers are used to read or modify data so that OSD
+ * can decide how to initialize the buffers: bring all the data for
+ * reads or just bring partial buffers for write. Note: the method does
+ * not check whether output array is large enough.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] pos position in the object to start
+ * \param[in] len size of region in bytes
+ * \param[out] lb array of descriptors to fill
+ * \param[in] maxlnb max slots in @lnb array
+ * \param[in] rw 0 if used to read, 1 if used for write
+ *
+ * \retval positive number of descriptors on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_bufs_get)(const struct lu_env *env,
+ struct dt_object *dt,
+ loff_t pos,
+ ssize_t len,
+ struct niobuf_local *lb,
+ int maxlnb,
+ enum dt_bufs_type rw);
+
+ /**
+ * Release reference granted by ->dbo_bufs_get().
+ *
+ * Release the reference granted by the previous ->dbo_bufs_get().
+ * Note the references are counted.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[out] lb array of descriptors to fill
+ * \param[in] nr size of the array
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_bufs_put)(const struct lu_env *env,
+ struct dt_object *dt,
+ struct niobuf_local *lb,
+ int nr);
+
+ /**
+ * Prepare buffers for reading.
+ *
+ * The method is called on the given buffers to fill them with data
+ * if that wasn't done in ->dbo_bufs_get(). The idea is that the
+ * caller should be able to get few buffers for discontiguous regions
+ * using few calls to ->dbo_bufs_get() and then request them all for
+ * the preparation with a single call, so that OSD can fire many I/Os
+ * to run concurrently. It's up to the specific OSD whether to implement
+ * this logic in ->dbo_read_prep() or just use ->dbo_bufs_get() to
+ * prepare data for every requested region individually.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] lnb array of buffer descriptors
+ * \param[in] nr size of the array
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_read_prep)(const struct lu_env *env,
+ struct dt_object *dt,
+ struct niobuf_local *lnb,
+ int nr);
+
+ /**
+ * Prepare buffers for write.
+ *
+ * This method is called on the given buffers to ensure the partial
+ * buffers contain correct data. The underlying idea is the same as
+ * in ->db_read_prep().
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] lb array of buffer descriptors
+ * \param[in] nr size of the array
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_write_prep)(const struct lu_env *env,
+ struct dt_object *dt,
+ struct niobuf_local *lb,
+ int nr);
+
+ /**
+ * Declare intention to write data stored in the buffers.
+ *
+ * Notify the underlying filesystem that data may be written in
+ * this transaction. This enables the layer below to prepare resources
+ * (e.g. journal credits in ext4). This method should be called
+ * between creating the transaction and starting it.
+ *
+ * If the layer implementing this method is responsible for quota,
+ * then the method should be reserving a space for the given
+ * credentials and return an error if quota is exceeded. If the write
+ * later fails for some reason, then the reserve should be released
+ * properly (usually in ->dt_trans_stop()).
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] lb array of descriptors
+ * \param[in] nr size of the array
+ * \param[in] th transaction handle
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_declare_write_commit)(const struct lu_env *env,
+ struct dt_object *dt,
+ struct niobuf_local *lb,
+ int nr,
+ struct thandle *th);
+
+ /**
+ * Write to existing object.
+ *
+ * This method is used to write data to a persistent storage using
+ * the buffers returned by ->dbo_bufs_get(). The caller puts new
+ * data into the buffers using own mechanisms (e.g. direct transfer
+ * from a NIC). The method should maintain attr.la_size. Also,
+ * attr.la_blocks should be maintained but this can be done in lazy
+ * manner, when actual allocation happens.
+ *
+ * If the layer implementing this method is responsible for quota,
+ * then the method should maintain space accounting for the given
+ * credentials.
+ *
+ * user_size parameter is the apparent size of the file, ie the size
+ * of the clear text version of the file. It can differ from the actual
+ * amount of valuable data received when a file is encrypted,
+ * because encrypted pages always contain PAGE_SIZE bytes of data,
+ * even if clear text data is only a few bytes.
+ * In case of encrypted file, apparent size will be stored as the inode
+ * size, so that servers return to clients an object size they can use
+ * to determine clear text size.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] lb array of descriptors for the buffers
+ * \param[in] nr size of the array
+ * \param[in] th transaction handle
+ * \param[in] user_size apparent size
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_write_commit)(const struct lu_env *env,
+ struct dt_object *dt,
+ struct niobuf_local *lb,
+ int nr,
+ struct thandle *th,
+ __u64 user_size);
+
+ /**
+ * Return logical to physical block mapping for a given extent
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] fm describe the region to map and the output buffer
+ * see the details in include/linux/fiemap.h
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_fiemap_get)(const struct lu_env *env,
+ struct dt_object *dt,
+ struct fiemap *fm);
+
+ /**
+ * Declare intention to deallocate space from an object.
+ *
+ * Notify the underlying filesystem that space may be deallocated in
+ * this transactions. This enables the layer below to prepare resources
+ * (e.g. journal credits in ext4). This method should be called between
+ * creating the transaction and starting it. The object need not exist.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] start the start of the region to deallocate
+ * \param[in] end the end of the region to deallocate
+ * \param[in] th transaction handle
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_declare_punch)(const struct lu_env *env,
+ struct dt_object *dt,
+ __u64 start,
+ __u64 end,
+ struct thandle *th);
+
+ /**
+ * Deallocate specified region in an object.
+ *
+ * This method is used to deallocate (release) space possibly consumed
+ * by the given region of the object. If the layer implementing this
+ * method is responsible for quota, then the method should maintain
+ * space accounting for the given credentials.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] start the start of the region to deallocate
+ * \param[in] end the end of the region to deallocate
+ * \param[in] th transaction handle
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_punch)(const struct lu_env *env,
+ struct dt_object *dt,
+ __u64 start,
+ __u64 end,
+ struct thandle *th);
+ /**
+ * Give advices on specified region in an object.
+ *
+ * This method is used to give advices about access pattern on an
+ * given region of the object. The disk filesystem understands
+ * the advices and tunes cache/read-ahead policies.
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] start the start of the region affected
+ * \param[in] end the end of the region affected
+ * \param[in] advice advice type
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_ladvise)(const struct lu_env *env,
+ struct dt_object *dt,
+ __u64 start,
+ __u64 end,
+ enum lu_ladvise_type advice);
+
+ /**
+ * Declare intention to preallocate space for an object
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] th transaction handle
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_declare_fallocate)(const struct lu_env *env,
+ struct dt_object *dt, __u64 start,
+ __u64 end, int mode, struct thandle *th);
+ /**
+ * Allocate specified region for an object
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] start the start of the region to allocate
+ * \param[in] end the end of the region to allocate
+ * \param[in] mode fallocate mode
+ * \param[in] th transaction handle
+ *
+ * \retval 0 on success
+ * \retval negative negated errno on error
+ */
+ int (*dbo_fallocate)(const struct lu_env *env,
+ struct dt_object *dt,
+ __u64 start,
+ __u64 end,
+ int mode,
+ struct thandle *th);
+ /**
+ * Do SEEK_HOLE/SEEK_DATA request on object
+ *
+ * \param[in] env execution environment for this thread
+ * \param[in] dt object
+ * \param[in] offset the offset to start seek from
+ * \param[in] whence seek mode, SEEK_HOLE or SEEK_DATA
+ *
+ * \retval hole/data offset on success
+ * \retval negative negated errno on error
+ */
+ loff_t (*dbo_lseek)(const struct lu_env *env, struct dt_object *dt,
+ loff_t offset, int whence);