diff mbox

[01/11] public: adjust documentation following XSA-217

Message ID 594A58DF0200007800165034@prv-mh.provo.novell.com
State New, archived
Headers show

Commit Message

Jan Beulich June 21, 2017, 9:30 a.m. UTC
Signed-off-by: Jan Beulich <jbeulich@suse.com>
public: adjust documentation following XSA-217

Signed-off-by: Jan Beulich <jbeulich@suse.com>

--- a/xen/include/public/grant_table.h
+++ b/xen/include/public/grant_table.h
@@ -411,12 +411,13 @@ typedef struct gnttab_dump_table gnttab_
 DEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t);
 
 /*
- * GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The
- * foreign domain has previously registered its interest in the transfer via
- * <domid, ref>.
+ * GNTTABOP_transfer: Transfer <frame> to a foreign domain. The foreign domain
+ * has previously registered its interest in the transfer via <domid, ref>.
  *
  * Note that, even if the transfer fails, the specified page no longer belongs
  * to the calling domain *unless* the error is GNTST_bad_page.
+ *
+ * Note further that only PV guests can use this operation.
  */
 struct gnttab_transfer {
     /* IN parameters. */
--- a/xen/include/public/memory.h
+++ b/xen/include/public/memory.h
@@ -102,6 +102,8 @@ DEFINE_XEN_GUEST_HANDLE(xen_memory_reser
  * Returns zero on complete success, otherwise a negative error code.
  * On complete success then always @nr_exchanged == @in.nr_extents.
  * On partial success @nr_exchanged indicates how much work was done.
+ *
+ * Note that only PV guests can use this operation.
  */
 #define XENMEM_exchange             11
 struct xen_memory_exchange {

Comments

Andrew Cooper June 21, 2017, 11:26 a.m. UTC | #1
On 21/06/17 10:30, Jan Beulich wrote:
> Signed-off-by: Jan Beulich <jbeulich@suse.com>

Reviewed-by: Andrew Cooper <andrew.cooper3@citrix.com>
George Dunlap June 21, 2017, 3:44 p.m. UTC | #2
Jan,

When you have a long series like this, could you name the files in a way
that makes it easier for a shell script to get their order?  e.g.,
01-xsa217-doc.patch, 02-gnttab-xfer-xenheap.patch, &c?

Having to manually save-and-apply the name of each patch of an
eleven-patch series separately is fairly annoying.  If they started with
a number, I could save them all to the same directory and then use "for
patch in *.patch ; do..." to apply them.

(Using `git send-email` would also make things a lot easier...)

 -George

On 21/06/17 10:30, Jan Beulich wrote:
> Signed-off-by: Jan Beulich <jbeulich@suse.com>
> 
> --- a/xen/include/public/grant_table.h
> +++ b/xen/include/public/grant_table.h
> @@ -411,12 +411,13 @@ typedef struct gnttab_dump_table gnttab_
>  DEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t);
>  
>  /*
> - * GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The
> - * foreign domain has previously registered its interest in the transfer via
> - * <domid, ref>.
> + * GNTTABOP_transfer: Transfer <frame> to a foreign domain. The foreign domain
> + * has previously registered its interest in the transfer via <domid, ref>.
>   *
>   * Note that, even if the transfer fails, the specified page no longer belongs
>   * to the calling domain *unless* the error is GNTST_bad_page.
> + *
> + * Note further that only PV guests can use this operation.
>   */
>  struct gnttab_transfer {
>      /* IN parameters. */
> --- a/xen/include/public/memory.h
> +++ b/xen/include/public/memory.h
> @@ -102,6 +102,8 @@ DEFINE_XEN_GUEST_HANDLE(xen_memory_reser
>   * Returns zero on complete success, otherwise a negative error code.
>   * On complete success then always @nr_exchanged == @in.nr_extents.
>   * On partial success @nr_exchanged indicates how much work was done.
> + *
> + * Note that only PV guests can use this operation.
>   */
>  #define XENMEM_exchange             11
>  struct xen_memory_exchange {
> 
> 
>
Jan Beulich June 21, 2017, 3:54 p.m. UTC | #3
>>> On 21.06.17 at 17:44, <george.dunlap@citrix.com> wrote:
> When you have a long series like this, could you name the files in a way
> that makes it easier for a shell script to get their order?  e.g.,
> 01-xsa217-doc.patch, 02-gnttab-xfer-xenheap.patch, &c?
> 
> Having to manually save-and-apply the name of each patch of an
> eleven-patch series separately is fairly annoying.  If they started with
> a number, I could save them all to the same directory and then use "for
> patch in *.patch ; do..." to apply them.
> 
> (Using `git send-email` would also make things a lot easier...)

Well, that's kind of difficult without using git for development work.
I can try to remember to name patches suitably, but that's
another manual step for me then, and while I continue to attach
files I would have hoped that the mail bodies nowadays come
through uncorrupted (and hence I'd expect file names to be
chosen by your mail client based on subject, which includes
numbering - that's at least how mine behaves - and there being
no actual need to use the attachments).

Jan
George Dunlap June 21, 2017, 4:53 p.m. UTC | #4
On 21/06/17 16:54, Jan Beulich wrote:
>>>> On 21.06.17 at 17:44, <george.dunlap@citrix.com> wrote:
>> When you have a long series like this, could you name the files in a way
>> that makes it easier for a shell script to get their order?  e.g.,
>> 01-xsa217-doc.patch, 02-gnttab-xfer-xenheap.patch, &c?
>>
>> Having to manually save-and-apply the name of each patch of an
>> eleven-patch series separately is fairly annoying.  If they started with
>> a number, I could save them all to the same directory and then use "for
>> patch in *.patch ; do..." to apply them.
>>
>> (Using `git send-email` would also make things a lot easier...)
> 
> Well, that's kind of difficult without using git for development work.
> I can try to remember to name patches suitably, but that's
> another manual step for me then

Well, it's either an extra manual step for you, or an extra manual step
for every person who reviews your code.  You don't need to justify to me
why you don't want to use git for development.  However, it's not fair
to externalize the cost of your development preferences to everybody else.

When it's just one or two patches I'm willing to make some
accommodation, but a series like this it's too much.

> , and while I continue to attach
> files I would have hoped that the mail bodies nowadays come
> through uncorrupted (and hence I'd expect file names to be
> chosen by your mail client based on subject, which includes
> numbering - that's at least how mine behaves - and there being
> no actual need to use the attachments).

I don't have a simple way of saving the text of the mail message without
saving the attachment in-line in the file; so without writing a special
tool just for your messages, I can't easily apply the patches into the
git tree (so I can see the change in-situ).

It looks like the mail bodies might actually be uncorrupted now; so it's
possible that if you send the mail without attachments anymore I might
be able to use the same workflow for you as I use for everyone else
(which presumably would extend to other people who might want to review
your patches).  If you send a test mail (or perhaps a series) I can give
it a try.

 -George
Stefano Stabellini June 21, 2017, 5:55 p.m. UTC | #5
On Wed, 21 Jun 2017, George Dunlap wrote:
> On 21/06/17 16:54, Jan Beulich wrote:
> >>>> On 21.06.17 at 17:44, <george.dunlap@citrix.com> wrote:
> >> When you have a long series like this, could you name the files in a way
> >> that makes it easier for a shell script to get their order?  e.g.,
> >> 01-xsa217-doc.patch, 02-gnttab-xfer-xenheap.patch, &c?
> >>
> >> Having to manually save-and-apply the name of each patch of an
> >> eleven-patch series separately is fairly annoying.  If they started with
> >> a number, I could save them all to the same directory and then use "for
> >> patch in *.patch ; do..." to apply them.
> >>
> >> (Using `git send-email` would also make things a lot easier...)
> > 
> > Well, that's kind of difficult without using git for development work.
> > I can try to remember to name patches suitably, but that's
> > another manual step for me then
> 
> Well, it's either an extra manual step for you, or an extra manual step
> for every person who reviews your code.  You don't need to justify to me
> why you don't want to use git for development.  However, it's not fair
> to externalize the cost of your development preferences to everybody else.
> 
> When it's just one or two patches I'm willing to make some
> accommodation, but a series like this it's too much.

I don't use git either (I use guilt). My solution to this problem is to
`guilt push' all my patches, then export them back as patches from the
commits using `git format-patch'.
Jan Beulich June 22, 2017, 6:59 a.m. UTC | #6
>>> On 21.06.17 at 18:53, <george.dunlap@citrix.com> wrote:
> On 21/06/17 16:54, Jan Beulich wrote:
>>>>> On 21.06.17 at 17:44, <george.dunlap@citrix.com> wrote:
>>> When you have a long series like this, could you name the files in a way
>>> that makes it easier for a shell script to get their order?  e.g.,
>>> 01-xsa217-doc.patch, 02-gnttab-xfer-xenheap.patch, &c?
>>>
>>> Having to manually save-and-apply the name of each patch of an
>>> eleven-patch series separately is fairly annoying.  If they started with
>>> a number, I could save them all to the same directory and then use "for
>>> patch in *.patch ; do..." to apply them.
>>>
>>> (Using `git send-email` would also make things a lot easier...)
>> 
>> Well, that's kind of difficult without using git for development work.
>> I can try to remember to name patches suitably, but that's
>> another manual step for me then
> 
> Well, it's either an extra manual step for you, or an extra manual step
> for every person who reviews your code.

That's a good point (which in fact I did think of while replying),
yet with one questionable aspect: Patch reviewing doesn't
generally mean patch application. Afaic, it's very rare that I
find it necessary to apply a patch in order to review it. Hence
I'm not convinced this is an extra manual step for everyone
looking at the patch.

>  You don't need to justify to me
> why you don't want to use git for development.  However, it's not fair
> to externalize the cost of your development preferences to everybody else.
> 
> When it's just one or two patches I'm willing to make some
> accommodation, but a series like this it's too much.

As said - I'll try to remember next time.

>> , and while I continue to attach
>> files I would have hoped that the mail bodies nowadays come
>> through uncorrupted (and hence I'd expect file names to be
>> chosen by your mail client based on subject, which includes
>> numbering - that's at least how mine behaves - and there being
>> no actual need to use the attachments).
> 
> I don't have a simple way of saving the text of the mail message without
> saving the attachment in-line in the file; so without writing a special
> tool just for your messages, I can't easily apply the patches into the
> git tree (so I can see the change in-situ).

Oh, okay. Mail programs seem to be even more different than so
far I did think they would be.

> It looks like the mail bodies might actually be uncorrupted now; so it's
> possible that if you send the mail without attachments anymore I might
> be able to use the same workflow for you as I use for everyone else
> (which presumably would extend to other people who might want to review
> your patches).  If you send a test mail (or perhaps a series) I can give
> it a try.

Perhaps best if I try to remember to do this next time round when
Cc-ing you on (not to small) a patch (I don't think it really needs to
be a series for that purpose). Not having to attach patches would,
in the end, remove one manual step for me.

Jan
George Dunlap June 22, 2017, 9:52 a.m. UTC | #7
On 22/06/17 07:59, Jan Beulich wrote:
>>> , and while I continue to attach
>>> files I would have hoped that the mail bodies nowadays come
>>> through uncorrupted (and hence I'd expect file names to be
>>> chosen by your mail client based on subject, which includes
>>> numbering - that's at least how mine behaves - and there being
>>> no actual need to use the attachments).
>>
>> I don't have a simple way of saving the text of the mail message without
>> saving the attachment in-line in the file; so without writing a special
>> tool just for your messages, I can't easily apply the patches into the
>> git tree (so I can see the change in-situ).
> 
> Oh, okay. Mail programs seem to be even more different than so
> far I did think they would be.

Yes, I actually was surprised that I don't seem to be able to save the
messages without the attachments in my mailer.

>> It looks like the mail bodies might actually be uncorrupted now; so it's
>> possible that if you send the mail without attachments anymore I might
>> be able to use the same workflow for you as I use for everyone else
>> (which presumably would extend to other people who might want to review
>> your patches).  If you send a test mail (or perhaps a series) I can give
>> it a try.
> 
> Perhaps best if I try to remember to do this next time round when
> Cc-ing you on (not to small) a patch (I don't think it really needs to
> be a series for that purpose). Not having to attach patches would,
> in the end, remove one manual step for me.

Thanks.

 -George
diff mbox

Patch

--- a/xen/include/public/grant_table.h
+++ b/xen/include/public/grant_table.h
@@ -411,12 +411,13 @@  typedef struct gnttab_dump_table gnttab_
 DEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t);
 
 /*
- * GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The
- * foreign domain has previously registered its interest in the transfer via
- * <domid, ref>.
+ * GNTTABOP_transfer: Transfer <frame> to a foreign domain. The foreign domain
+ * has previously registered its interest in the transfer via <domid, ref>.
  *
  * Note that, even if the transfer fails, the specified page no longer belongs
  * to the calling domain *unless* the error is GNTST_bad_page.
+ *
+ * Note further that only PV guests can use this operation.
  */
 struct gnttab_transfer {
     /* IN parameters. */
--- a/xen/include/public/memory.h
+++ b/xen/include/public/memory.h
@@ -102,6 +102,8 @@  DEFINE_XEN_GUEST_HANDLE(xen_memory_reser
  * Returns zero on complete success, otherwise a negative error code.
  * On complete success then always @nr_exchanged == @in.nr_extents.
  * On partial success @nr_exchanged indicates how much work was done.
+ *
+ * Note that only PV guests can use this operation.
  */
 #define XENMEM_exchange             11
 struct xen_memory_exchange {