| Message ID | 1511426872-13980-1-git-send-email-jianjay.zhou@huawei.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
Hi, Does this document update make sense? Regards, Jay On 2017/11/23 16:47, Jay Zhou wrote: > Since the commit 11808bb0c422134bf09119f4aa22c59b0ce84bf3 removed > the put_buffer callback and using an iovec based write handler instead, > the docs should be sync with the code too. > > Signed-off-by: Jay Zhou <jianjay.zhou@huawei.com> > --- > docs/devel/migration.txt | 31 ++++++++++++++++++------------- > 1 file changed, 18 insertions(+), 13 deletions(-) > > diff --git a/docs/devel/migration.txt b/docs/devel/migration.txt > index 4030703..e7b08c9 100644 > --- a/docs/devel/migration.txt > +++ b/docs/devel/migration.txt > @@ -52,26 +52,31 @@ QEMU uses a QEMUFile abstraction to be able to do migration. Any type > of migration that wants to use QEMU infrastructure has to create a > QEMUFile with: > > -QEMUFile *qemu_fopen_ops(void *opaque, > - QEMUFilePutBufferFunc *put_buffer, > - QEMUFileGetBufferFunc *get_buffer, > - QEMUFileCloseFunc *close); > +typedef struct QEMUFileOps { > + QEMUFileGetBufferFunc *get_buffer; > + QEMUFileCloseFunc *close; > + QEMUFileSetBlocking *set_blocking; > + QEMUFileWritevBufferFunc *writev_buffer; > + QEMURetPathFunc *get_return_path; > + QEMUFileShutdownFunc *shut_down; > +} QEMUFileOps; > > -The functions have the following functionality: > +QEMUFile *qemu_fopen_ops(void *opaque, const QEMUFileOps *ops); > > -This function writes a chunk of data to a file at the given position. > -The pos argument can be ignored if the file is only used for > -streaming. The handler should try to write all of the data it can. > +The main functions of QEMUFileOps have the following functionality: > > -typedef int (QEMUFilePutBufferFunc)(void *opaque, const uint8_t *buf, > - int64_t pos, int size); > +This function writes an iovec to file. The handler must write all > +of the data or return a negative errno value. > + > +typedef ssize_t (QEMUFileWritevBufferFunc)(void *opaque, struct iovec *iov, > + int iovcnt, int64_t pos); > > Read a chunk of data from a file at the given position. The pos argument > can be ignored if the file is only be used for streaming. The number of > bytes actually read should be returned. > > -typedef int (QEMUFileGetBufferFunc)(void *opaque, uint8_t *buf, > - int64_t pos, int size); > +typedef ssize_t (QEMUFileGetBufferFunc)(void *opaque, uint8_t *buf, > + int64_t pos, int size); > > Close a file and return an error code. > > @@ -80,7 +85,7 @@ typedef int (QEMUFileCloseFunc)(void *opaque); > You can use any internal state that you need using the opaque void * > pointer that is passed to all functions. > > -The important functions for us are put_buffer()/get_buffer() that > +The important functions for us are writev_buffer()/get_buffer() that > allow to write/read a buffer into the QEMUFile. > > === How to save the state of one device === >
* Jay Zhou (jianjay.zhou@huawei.com) wrote: > Since the commit 11808bb0c422134bf09119f4aa22c59b0ce84bf3 removed > the put_buffer callback and using an iovec based write handler instead, > the docs should be sync with the code too. > > Signed-off-by: Jay Zhou <jianjay.zhou@huawei.com> Lets check with Dan (added to cc) since he wrote 11808bb; it might be best just to rever to migration/qemu-file.h for an explanation of each function. Dave > --- > docs/devel/migration.txt | 31 ++++++++++++++++++------------- > 1 file changed, 18 insertions(+), 13 deletions(-) > > diff --git a/docs/devel/migration.txt b/docs/devel/migration.txt > index 4030703..e7b08c9 100644 > --- a/docs/devel/migration.txt > +++ b/docs/devel/migration.txt > @@ -52,26 +52,31 @@ QEMU uses a QEMUFile abstraction to be able to do migration. Any type > of migration that wants to use QEMU infrastructure has to create a > QEMUFile with: > > -QEMUFile *qemu_fopen_ops(void *opaque, > - QEMUFilePutBufferFunc *put_buffer, > - QEMUFileGetBufferFunc *get_buffer, > - QEMUFileCloseFunc *close); > +typedef struct QEMUFileOps { > + QEMUFileGetBufferFunc *get_buffer; > + QEMUFileCloseFunc *close; > + QEMUFileSetBlocking *set_blocking; > + QEMUFileWritevBufferFunc *writev_buffer; > + QEMURetPathFunc *get_return_path; > + QEMUFileShutdownFunc *shut_down; > +} QEMUFileOps; > > -The functions have the following functionality: > +QEMUFile *qemu_fopen_ops(void *opaque, const QEMUFileOps *ops); > > -This function writes a chunk of data to a file at the given position. > -The pos argument can be ignored if the file is only used for > -streaming. The handler should try to write all of the data it can. > +The main functions of QEMUFileOps have the following functionality: > > -typedef int (QEMUFilePutBufferFunc)(void *opaque, const uint8_t *buf, > - int64_t pos, int size); > +This function writes an iovec to file. The handler must write all > +of the data or return a negative errno value. > + > +typedef ssize_t (QEMUFileWritevBufferFunc)(void *opaque, struct iovec *iov, > + int iovcnt, int64_t pos); > > Read a chunk of data from a file at the given position. The pos argument > can be ignored if the file is only be used for streaming. The number of > bytes actually read should be returned. > > -typedef int (QEMUFileGetBufferFunc)(void *opaque, uint8_t *buf, > - int64_t pos, int size); > +typedef ssize_t (QEMUFileGetBufferFunc)(void *opaque, uint8_t *buf, > + int64_t pos, int size); > > Close a file and return an error code. > > @@ -80,7 +85,7 @@ typedef int (QEMUFileCloseFunc)(void *opaque); > You can use any internal state that you need using the opaque void * > pointer that is passed to all functions. > > -The important functions for us are put_buffer()/get_buffer() that > +The important functions for us are writev_buffer()/get_buffer() that > allow to write/read a buffer into the QEMUFile. > > === How to save the state of one device === > -- > 1.8.3.1 > > -- Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK
On Tue, Dec 05, 2017 at 07:58:16PM +0000, Dr. David Alan Gilbert wrote: > * Jay Zhou (jianjay.zhou@huawei.com) wrote: > > Since the commit 11808bb0c422134bf09119f4aa22c59b0ce84bf3 removed > > the put_buffer callback and using an iovec based write handler instead, > > the docs should be sync with the code too. > > > > Signed-off-by: Jay Zhou <jianjay.zhou@huawei.com> > > Lets check with Dan (added to cc) since he wrote 11808bb; > it might be best just to rever to migration/qemu-file.h for an > explanation of each function. The updates look ok, but I tend to think this entire section of migrate.txt should be deleted, in favour of the inline APIs docs in mijgration/qemu-file.h As a developer the header file is where I would look for this kind of API description. The migration.txt can just point epople to the header file for API docs. Regards, Daniel
* Daniel P. Berrange (berrange@redhat.com) wrote: > On Tue, Dec 05, 2017 at 07:58:16PM +0000, Dr. David Alan Gilbert wrote: > > * Jay Zhou (jianjay.zhou@huawei.com) wrote: > > > Since the commit 11808bb0c422134bf09119f4aa22c59b0ce84bf3 removed > > > the put_buffer callback and using an iovec based write handler instead, > > > the docs should be sync with the code too. > > > > > > Signed-off-by: Jay Zhou <jianjay.zhou@huawei.com> > > > > Lets check with Dan (added to cc) since he wrote 11808bb; > > it might be best just to rever to migration/qemu-file.h for an > > explanation of each function. > > The updates look ok, but I tend to think this entire section of > migrate.txt should be deleted, in favour of the inline APIs > docs in mijgration/qemu-file.h As a developer the header file > is where I would look for this kind of API description. The > migration.txt can just point epople to the header file for API > docs. OK, I'll do that on top of my rework to rst. Sorry Jay! Dave > > Regards, > Daniel > -- > |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| > |: https://libvirt.org -o- https://fstop138.berrange.com :| > |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :| -- Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK
> -----Original Message----- > From: Dr. David Alan Gilbert [mailto:dgilbert@redhat.com] > Sent: Friday, December 15, 2017 11:15 PM > To: Daniel P. Berrange <berrange@redhat.com> > Cc: Zhoujian (jay) <jianjay.zhou@huawei.com>; qemu-devel@nongnu.org; > quintela@redhat.com; Huangweidong (C) <weidong.huang@huawei.com>; wangxin > (U) <wangxinxin.wang@huawei.com> > Subject: Re: [PATCH] docs/devel/migration.txt: keep functions consistent > with the code > > * Daniel P. Berrange (berrange@redhat.com) wrote: > > On Tue, Dec 05, 2017 at 07:58:16PM +0000, Dr. David Alan Gilbert wrote: > > > * Jay Zhou (jianjay.zhou@huawei.com) wrote: > > > > Since the commit 11808bb0c422134bf09119f4aa22c59b0ce84bf3 removed > > > > the put_buffer callback and using an iovec based write handler > > > > instead, the docs should be sync with the code too. > > > > > > > > Signed-off-by: Jay Zhou <jianjay.zhou@huawei.com> > > > > > > Lets check with Dan (added to cc) since he wrote 11808bb; it might > > > be best just to rever to migration/qemu-file.h for an explanation of > > > each function. > > > > The updates look ok, but I tend to think this entire section of > > migrate.txt should be deleted, in favour of the inline APIs > > docs in mijgration/qemu-file.h As a developer the header file > > is where I would look for this kind of API description. The > > migration.txt can just point epople to the header file for API docs. Yes, agreed. > > OK, I'll do that on top of my rework to rst. > It's OK for me. :) Regards, Jay
diff --git a/docs/devel/migration.txt b/docs/devel/migration.txt index 4030703..e7b08c9 100644 --- a/docs/devel/migration.txt +++ b/docs/devel/migration.txt @@ -52,26 +52,31 @@ QEMU uses a QEMUFile abstraction to be able to do migration. Any type of migration that wants to use QEMU infrastructure has to create a QEMUFile with: -QEMUFile *qemu_fopen_ops(void *opaque, - QEMUFilePutBufferFunc *put_buffer, - QEMUFileGetBufferFunc *get_buffer, - QEMUFileCloseFunc *close); +typedef struct QEMUFileOps { + QEMUFileGetBufferFunc *get_buffer; + QEMUFileCloseFunc *close; + QEMUFileSetBlocking *set_blocking; + QEMUFileWritevBufferFunc *writev_buffer; + QEMURetPathFunc *get_return_path; + QEMUFileShutdownFunc *shut_down; +} QEMUFileOps; -The functions have the following functionality: +QEMUFile *qemu_fopen_ops(void *opaque, const QEMUFileOps *ops); -This function writes a chunk of data to a file at the given position. -The pos argument can be ignored if the file is only used for -streaming. The handler should try to write all of the data it can. +The main functions of QEMUFileOps have the following functionality: -typedef int (QEMUFilePutBufferFunc)(void *opaque, const uint8_t *buf, - int64_t pos, int size); +This function writes an iovec to file. The handler must write all +of the data or return a negative errno value. + +typedef ssize_t (QEMUFileWritevBufferFunc)(void *opaque, struct iovec *iov, + int iovcnt, int64_t pos); Read a chunk of data from a file at the given position. The pos argument can be ignored if the file is only be used for streaming. The number of bytes actually read should be returned. -typedef int (QEMUFileGetBufferFunc)(void *opaque, uint8_t *buf, - int64_t pos, int size); +typedef ssize_t (QEMUFileGetBufferFunc)(void *opaque, uint8_t *buf, + int64_t pos, int size); Close a file and return an error code. @@ -80,7 +85,7 @@ typedef int (QEMUFileCloseFunc)(void *opaque); You can use any internal state that you need using the opaque void * pointer that is passed to all functions. -The important functions for us are put_buffer()/get_buffer() that +The important functions for us are writev_buffer()/get_buffer() that allow to write/read a buffer into the QEMUFile. === How to save the state of one device ===
Since the commit 11808bb0c422134bf09119f4aa22c59b0ce84bf3 removed the put_buffer callback and using an iovec based write handler instead, the docs should be sync with the code too. Signed-off-by: Jay Zhou <jianjay.zhou@huawei.com> --- docs/devel/migration.txt | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-)