block: Documentation improvment
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
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
@@ -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
@@ -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
@@ -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
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
@@ -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
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
@@ -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
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
@@ -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
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.
Signed-off-by Philippe Mathieu-Daudé <[email protected]>---
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.
+ */
intblk_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_toffset, const void *buf, int bytes,BdrvRequestFlags flags);
int64_tblk_getlength(BlockBackend *blk);
Signature · 3 lines
Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
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
@@ -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