[v4] block: document semantics of bdrv_co_preadv|pwritev

Commit Message

Daniel P. Berrangé Aug. 31, 2017, 10:54 a.m. UTC

Reviewed-by: Stefan Hajnoczi <[e-mail]>
Reviewed-by: Eric Blake <[e-mail]>
Signed-off-by: Daniel P. Berrange <[e-mail]>
---

Changed in v4:

  - Fix typo in commit message

 include/block/block_int.h | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

Comments

Kevin Wolf Sept. 5, 2017, 9:40 a.m. UTC | #1

Am 31.08.2017 um 12:54 hat Daniel P. Berrange geschrieben:
> Reviewed-by: Stefan Hajnoczi <[e-mail]>
> Reviewed-by: Eric Blake <[e-mail]>
> Signed-off-by: Daniel P. Berrange <[e-mail]>

Thanks, applied to the block branch.

Kevin

Stefan Hajnoczi Sept. 5, 2017, 10:07 a.m. UTC | #2

On Thu, Aug 31, 2017 at 11:54:56AM +0100, Daniel P. Berrange wrote:
> Reviewed-by: Stefan Hajnoczi <[e-mail]>
> Reviewed-by: Eric Blake <[e-mail]>
> Signed-off-by: Daniel P. Berrange <[e-mail]>
> ---
> 
> Changed in v4:
> 
>   - Fix typo in commit message
> 
>  include/block/block_int.h | 31 +++++++++++++++++++++++++++++++
>  1 file changed, 31 insertions(+)

Thanks, applied to my block tree:
https://github.com/stefanha/qemu/commits/block

Stefan

Patch

diff --git a/include/block/block_int.h b/include/block/block_int.h
index 7571c0aaaf..7816b43a27 100644
--- a/include/block/block_int.h
+++ b/include/block/block_int.h
@@ -146,12 +146,43 @@  struct BlockDriver {
 
     int coroutine_fn (*bdrv_co_readv)(BlockDriverState *bs,
         int64_t sector_num, int nb_sectors, QEMUIOVector *qiov);
+
+    /**
+     * @offset: position in bytes to read at
+     * @bytes: number of bytes to read
+     * @qiov: the buffers to fill with read data
+     * @flags: currently unused, always 0
+     *
+     * @offset and @bytes will be a multiple of 'request_alignment',
+     * but the length of individual @qiov elements does not have to
+     * be a multiple.
+     *
+     * @bytes will always equal the total size of @qiov, and will be
+     * no larger than 'max_transfer'.
+     *
+     * The buffer in @qiov may point directly to guest memory.
+     */
     int coroutine_fn (*bdrv_co_preadv)(BlockDriverState *bs,
         uint64_t offset, uint64_t bytes, QEMUIOVector *qiov, int flags);
     int coroutine_fn (*bdrv_co_writev)(BlockDriverState *bs,
         int64_t sector_num, int nb_sectors, QEMUIOVector *qiov);
     int coroutine_fn (*bdrv_co_writev_flags)(BlockDriverState *bs,
         int64_t sector_num, int nb_sectors, QEMUIOVector *qiov, int flags);
+    /**
+     * @offset: position in bytes to write at
+     * @bytes: number of bytes to write
+     * @qiov: the buffers containing data to write
+     * @flags: zero or more bits allowed by 'supported_write_flags'
+     *
+     * @offset and @bytes will be a multiple of 'request_alignment',
+     * but the length of individual @qiov elements does not have to
+     * be a multiple.
+     *
+     * @bytes will always equal the total size of @qiov, and will be
+     * no larger than 'max_transfer'.
+     *
+     * The buffer in @qiov may point directly to guest memory.
+     */
     int coroutine_fn (*bdrv_co_pwritev)(BlockDriverState *bs,
         uint64_t offset, uint64_t bytes, QEMUIOVector *qiov, int flags);