Skip to contentSkip to conversation

block: Documentation improvment

PATCH In review Philippe Mathieu-Daudé 2 participants 7 messages May 15, 2020

lore
Share & tools
lore
#0 lore raw

v2 cover block: Documentation improvment

These patches contain documentation I wrote down while looking at the code.

Supersedes: <[email protected]>

Philippe Mathieu-Daudé (5):
qemu/osdep: Document qemu_memalign() and friends qemu/bitmap: Document bitmap_new() returned pointer block/block: Document BlockSizes fields sysemu/block-backend: Document blk_read()/blk_pwrite() sysemu/block-backend: Document blk_get_max_iov() returned value

 include/block/block.h          |  8 ++++++--
 include/qemu/bitmap.h          |  2 ++
 include/qemu/osdep.h           |  3 +++
 include/sysemu/block-backend.h | 27 +++++++++++++++++++++++++++
 4 files changed, 38 insertions(+), 2 deletions(-)
Signature · 1 line
2.21.3
#1 lore raw

PATCH v2 1/5 qemu/osdep: Document qemu_memalign() and friends

Document allocator functions that require a specific de-allocator call.

---
 include/block/block.h          | 4 ++++
 include/qemu/osdep.h           | 3 +++
 include/sysemu/block-backend.h | 2 ++
 3 files changed, 9 insertions(+)
include/block/block.h +4 -0
index 4de8d8f8a6..480e6b6837 100644
@@ -525,9 +525,13 @@ void bdrv_img_create(const char *filename, const char *fmt,
 size_t bdrv_min_mem_align(BlockDriverState *bs);
 /* Returns optimal alignment in bytes for bounce buffer */
 size_t bdrv_opt_mem_align(BlockDriverState *bs);
+/* callers must free the returned pointer with qemu_vfree() */
 void *qemu_blockalign(BlockDriverState *bs, size_t size);
+/* callers must free the returned pointer with qemu_vfree() */
 void *qemu_blockalign0(BlockDriverState *bs, size_t size);
+/* callers must free the returned pointer with qemu_vfree() */
 void *qemu_try_blockalign(BlockDriverState *bs, size_t size);
+/* callers must free the returned pointer with qemu_vfree() */
 void *qemu_try_blockalign0(BlockDriverState *bs, size_t size);
 bool bdrv_qiov_is_aligned(BlockDriverState *bs, QEMUIOVector *qiov);
 
include/qemu/osdep.h +3 -0
index ff7c17b857..b3eccce762 100644
@@ -294,8 +294,11 @@ extern int daemon(int, int);
 #endif
 
 int qemu_daemon(int nochdir, int noclose);
+/* callers must free the returned pointer with qemu_vfree() */
 void *qemu_try_memalign(size_t alignment, size_t size);
+/* callers must free the returned pointer with qemu_vfree() */
 void *qemu_memalign(size_t alignment, size_t size);
+/* callers must free the returned pointer with qemu_anon_ram_free() */
 void *qemu_anon_ram_alloc(size_t size, uint64_t *align, bool shared);
 void qemu_vfree(void *ptr);
 void qemu_anon_ram_free(void *ptr, size_t size);
include/sysemu/block-backend.h +2 -0
index 0917663d89..7996cb61bb 100644
@@ -205,7 +205,9 @@ uint32_t blk_get_request_alignment(BlockBackend *blk);
 uint32_t blk_get_max_transfer(BlockBackend *blk);
 int blk_get_max_iov(BlockBackend *blk);
 void blk_set_guest_block_size(BlockBackend *blk, int align);
+/* callers must free the returned pointer with qemu_vfree() */
 void *blk_try_blockalign(BlockBackend *blk, size_t size);
+/* callers must free the returned pointer with qemu_vfree() */
 void *blk_blockalign(BlockBackend *blk, size_t size);
 bool blk_op_is_blocked(BlockBackend *blk, BlockOpType op, Error **errp);
 void blk_op_unblock(BlockBackend *blk, BlockOpType op, Error *reason);
Signature · 1 line
2.21.3
#2 lore raw

PATCH v2 2/5 qemu/bitmap: Document bitmap_new() returned pointer

In reply to Philippe Mathieu-Daudé
---
 include/qemu/bitmap.h | 2 ++
 1 file changed, 2 insertions(+)
include/qemu/bitmap.h +2 -0
index 82a1d2f41f..0b390ff576 100644
@@ -90,12 +90,14 @@ int slow_bitmap_intersects(const unsigned long *bitmap1,
                            const unsigned long *bitmap2, long bits);
 long slow_bitmap_count_one(const unsigned long *bitmap, long nbits);
 
+/* callers must free the returned pointer with g_free() */
 static inline unsigned long *bitmap_try_new(long nbits)
 {
     long len = BITS_TO_LONGS(nbits) * sizeof(unsigned long);
     return g_try_malloc0(len);
 }
 
+/* callers must free the returned pointer with g_free() */
 static inline unsigned long *bitmap_new(long nbits)
 {
     unsigned long *ptr = bitmap_try_new(nbits);
Signature · 1 line
2.21.3
#3 lore raw

PATCH v2 3/5 block/block: Document BlockSizes fields

In reply to Philippe Mathieu-Daudé

As it is not obvious for a block neophyte what means the 'log' value, document it.

---
 include/block/block.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/block/block.h +2 -2
index 480e6b6837..6836876da1 100644
@@ -86,8 +86,8 @@ typedef enum {
 } BdrvRequestFlags;
 
 typedef struct BlockSizes {
-    uint32_t phys;
-    uint32_t log;
+    uint32_t phys;  /* physical block size */
+    uint32_t log;   /* logical block size */
 } BlockSizes;
 
 typedef struct HDGeometry {
Signature · 1 line
2.21.3
#4 lore raw

PATCH v2 4/5 sysemu/block-backend: Document blk_read()/blk_pwrite()

In reply to Philippe Mathieu-Daudé

The blk_read()/blk_pwrite() return value is not obvious, document it.

---
v2: 's/ - /: /' (stefanha)

---
 include/sysemu/block-backend.h | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
include/sysemu/block-backend.h +24 -0
index 7996cb61bb..b693dfb8f0 100644
@@ -155,7 +155,31 @@ BlockAIOCB *blk_aio_pwrite_zeroes(BlockBackend *blk, int64_t offset,
                                   int bytes, BdrvRequestFlags flags,
                                   BlockCompletionFunc *cb, void *opaque);
 int blk_make_zero(BlockBackend *blk, BdrvRequestFlags flags);
+
+/**
+ * blk_pread:
+ *
+ * @blk: the block backend where the buffer content is going to be read from
+ * @offset: position in bytes to read at
+ * @buf: the data buffer
+ * @bytes: number of bytes to read
+ *
+ * Returns: the number of bytes read on success, or a negative errno otherwise.
+ */
 int blk_pread(BlockBackend *blk, int64_t offset, void *buf, int bytes);
+
+/**
+ * blk_pwrite:
+ *
+ * @blk: the block backend where the buffer content is going to be written to
+ * @offset: position in bytes to write at
+ * @buf: the data buffer
+ * @bytes: number of bytes of @buf to write
+ * @flags: request flags
+ *
+ * Returns: the number of bytes consumed on success,
+ *          or a negative errno otherwise.
+ */
 int blk_pwrite(BlockBackend *blk, int64_t offset, const void *buf, int bytes,
                BdrvRequestFlags flags);
 int64_t blk_getlength(BlockBackend *blk);
Signature · 1 line
2.21.3
#5 lore raw

Re: [PATCH v2 4/5] sysemu/block-backend: Document blk_read()/blk_pwrite()

Quoted 1 line · Philippe Mathieu-Daudé

The blk_read()/blk_pwrite() return value is not obvious,

s/read/pread/ here and in the subject

Quoted 5 lines

document it.

---

Quoted 11 lines

+/**
+ * blk_pread:
+ *
+ * @blk: the block backend where the buffer content is going to be read from
+ * @offset: position in bytes to read at
+ * @buf: the data buffer
+ * @bytes: number of bytes to read
+ *
+ * Returns: the number of bytes read on success, or a negative errno otherwise.
+ */
int blk_pread(BlockBackend *blk, int64_t offset, void *buf, int bytes);

"the number of bytes read" is ambiguous - it sounds too much like the read() syscall where short reads are successful. But blk_pread() never does short reads, on success, the result is exactly 'bytes'.

include/sysemu/block-backend.h BlockAIOCB *blk_aio_pwrite_zeroes(BlockBackend *blk, int64_t offset, · line 180

Quoted 11 lines
include/sysemu/block-backend.h +11 -0
+
+/**
+ * blk_pwrite:
+ *
+ * @blk: the block backend where the buffer content is going to be written to
+ * @offset: position in bytes to write at
+ * @buf: the data buffer
+ * @bytes: number of bytes of @buf to write
+ * @flags: request flags
+ *
+ * Returns: the number of bytes consumed on success,

Ditto - we don't support short writes, so on success, it is always 'bytes'.

Quoted 6 lines

+ * or a negative errno otherwise.
+ */
int blk_pwrite(BlockBackend *blk, int64_t offset, const void *buf, int bytes,

                 BdrvRequestFlags flags);

int64_t blk_getlength(BlockBackend *blk);

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
#6 lore raw

PATCH v2 5/5 sysemu/block-backend: Document blk_get_max_iov() returned value

In reply to Philippe Mathieu-Daudé
---
 include/sysemu/block-backend.h | 1 +
 1 file changed, 1 insertion(+)
include/sysemu/block-backend.h +1 -0
index b693dfb8f0..7b12563c65 100644
@@ -227,6 +227,7 @@ void blk_eject(BlockBackend *blk, bool eject_flag);
 int blk_get_flags(BlockBackend *blk);
 uint32_t blk_get_request_alignment(BlockBackend *blk);
 uint32_t blk_get_max_transfer(BlockBackend *blk);
+/* Returns the maximum number of iovec elements */
 int blk_get_max_iov(BlockBackend *blk);
 void blk_set_guest_block_size(BlockBackend *blk, int align);
 /* callers must free the returned pointer with qemu_vfree() */
Signature · 1 line
2.21.3