[PATCH] xen/arm: Update documentation in the public header arch-arm.h

[PATCH] xen/arm: Update documentation in the public header arch-arm.h

[Julien Grall]

Minor updates to the documentation in xen/include/public/arch-arm.h:
    - Comments coding style fix
    - Typoes
    - Update the list of supported hypercalls by ARM
    - Remove uncessary comment about 64bit.

Signed-off-by: Julien Grall <julien.grall@linaro.org>
Cc: Ian Jackson <ian.jackson@eu.citrix.com>
Cc: Jan Beulich <jbeulich@suse.com>
Cc: Keir Fraser <keir@xen.org>

---
    I'm not sure if we usually backport documentation. If so, I'd like
    to request backporting for Xen 4.5.
---
 xen/include/public/arch-arm.h | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/xen/include/public/arch-arm.h b/xen/include/public/arch-arm.h
index 72d641f..ae294fa 100644
--- a/xen/include/public/arch-arm.h
+++ b/xen/include/public/arch-arm.h
@@ -87,15 +87,10 @@
  * unavailable/unsupported.
  *
  *  HYPERVISOR_memory_op
- *   All generic sub-operations.
- *
- *   In addition the following arch specific sub-ops:
- *    * XENMEM_add_to_physmap
- *    * XENMEM_add_to_physmap_batch
+ *   All generic sub-operations
  *
  *  HYPERVISOR_domctl
  *   All generic sub-operations, with the exception of:
- *    * XEN_DOMCTL_iomem_permission (not yet implemented)
  *    * XEN_DOMCTL_irq_permission (not yet implemented)
  *
  *  HYPERVISOR_sched_op
@@ -183,7 +178,7 @@
  * XEN_GUEST_HANDLE represents a guest pointer, when passed as a field
  * in a struct in memory. On ARM is always 8 bytes sizes and 8 bytes
  * aligned.
- * XEN_GUEST_HANDLE_PARAM represent a guest pointer, when passed as an
+ * XEN_GUEST_HANDLE_PARAM represents a guest pointer, when passed as an
  * hypercall argument. It is 4 bytes on aarch and 8 bytes on aarch64.
  */
 #define __DEFINE_XEN_GUEST_HANDLE(name, type) \
@@ -192,7 +187,6 @@
 #define DEFINE_XEN_GUEST_HANDLE(name)   __DEFINE_XEN_GUEST_HANDLE(name, name)
 #define __XEN_GUEST_HANDLE(name)        __guest_handle_64_ ## name
 #define XEN_GUEST_HANDLE(name)          __XEN_GUEST_HANDLE(name)
-/* this is going to be changed on 64 bit */
 #define XEN_GUEST_HANDLE_PARAM(name)    __guest_handle_ ## name
 #define set_xen_guest_handle_raw(hnd, val)                  \
     do {                                                    \
@@ -318,7 +312,7 @@ typedef uint64_t xen_callback_t;
 
 #if defined(__XEN__) || defined(__XEN_TOOLS__)
 
-/* PSR bits (CPSR, SPSR)*/
+/* PSR bits (CPSR, SPSR) */
 
 #define PSR_THUMB       (1<<5)        /* Thumb Mode enable */
 #define PSR_FIQ_MASK    (1<<6)        /* Fast Interrupt mask */
@@ -374,7 +368,8 @@ typedef uint64_t xen_callback_t;
 
 /* Physical Address Space */
 
-/* vGIC mappings: Only one set of mapping is used by the guest.
+/*
+ * vGIC mappings: Only one set of mapping is used by the guest.
  * Therefore they can overlap.
  */
 
@@ -394,7 +389,8 @@ typedef uint64_t xen_callback_t;
 #define GUEST_GICV3_GICR0_BASE     0x03020000ULL    /* vCPU0 - vCPU7 */
 #define GUEST_GICV3_GICR0_SIZE     0x00100000ULL
 
-/* 16MB == 4096 pages reserved for guest to use as a region to map its
+/*
+ * 16MB == 4096 pages reserved for guest to use as a region to map its
  * grant table in.
  */
 #define GUEST_GNTTAB_BASE 0x38000000ULL
-- 
2.1.4

Re: [PATCH] xen/arm: Update documentation in the public header arch-arm.h

[Ian Campbell]

On Wed, 2015-01-14 at 12:53 +0000, Julien Grall wrote:
> Minor updates to the documentation in xen/include/public/arch-arm.h:
>     - Comments coding style fix
>     - Typoes
>     - Update the list of supported hypercalls by ARM
>     - Remove uncessary comment about 64bit.

"unnecessary"

> Signed-off-by: Julien Grall <julien.grall@linaro.org>
> Cc: Ian Jackson <ian.jackson@eu.citrix.com>
> Cc: Jan Beulich <jbeulich@suse.com>
> Cc: Keir Fraser <keir@xen.org>
> 
> ---
>     I'm not sure if we usually backport documentation. If so, I'd like
>     to request backporting for Xen 4.5.

I don't think we need to TBH, any development should be against unstable
and we publish these headers online for ease of access.

> + *   All generic sub-operations
>   *
>   *  HYPERVISOR_domctl
>   *   All generic sub-operations, with the exception of:
> - *    * XEN_DOMCTL_iomem_permission (not yet implemented)
>   *    * XEN_DOMCTL_irq_permission (not yet implemented)
>   *
>   *  HYPERVISOR_sched_op
> @@ -183,7 +178,7 @@
>   * XEN_GUEST_HANDLE represents a guest pointer, when passed as a field
>   * in a struct in memory. On ARM is always 8 bytes sizes and 8 bytes
>   * aligned.
> - * XEN_GUEST_HANDLE_PARAM represent a guest pointer, when passed as an
> + * XEN_GUEST_HANDLE_PARAM represents a guest pointer, when passed as an
>   * hypercall argument. It is 4 bytes on aarch and 8 bytes on aarch64.

Is there a "32" missing in this last sentence do you think? (not the bit
you touched)

I can fix the "unnecessary" on commit, so:
Acked-by: Ian Campbell <ian.campbell@citrix.com>

Ian.

Re: [PATCH] xen/arm: Update documentation in the public header arch-arm.h

[Julien Grall]

Hi,

On 15/01/15 13:48, Ian Campbell wrote:
> On Wed, 2015-01-14 at 12:53 +0000, Julien Grall wrote:
>> Minor updates to the documentation in xen/include/public/arch-arm.h:
>>     - Comments coding style fix
>>     - Typoes
>>     - Update the list of supported hypercalls by ARM
>>     - Remove uncessary comment about 64bit.
> 
> "unnecessary"
> 
>> Signed-off-by: Julien Grall <julien.grall@linaro.org>
>> Cc: Ian Jackson <ian.jackson@eu.citrix.com>
>> Cc: Jan Beulich <jbeulich@suse.com>
>> Cc: Keir Fraser <keir@xen.org>
>>
>> ---
>>     I'm not sure if we usually backport documentation. If so, I'd like
>>     to request backporting for Xen 4.5.
> 
> I don't think we need to TBH, any development should be against unstable
> and we publish these headers online for ease of access.

Ok. I'm fine with that.

>> + *   All generic sub-operations
>>   *
>>   *  HYPERVISOR_domctl
>>   *   All generic sub-operations, with the exception of:
>> - *    * XEN_DOMCTL_iomem_permission (not yet implemented)
>>   *    * XEN_DOMCTL_irq_permission (not yet implemented)
>>   *
>>   *  HYPERVISOR_sched_op
>> @@ -183,7 +178,7 @@
>>   * XEN_GUEST_HANDLE represents a guest pointer, when passed as a field
>>   * in a struct in memory. On ARM is always 8 bytes sizes and 8 bytes
>>   * aligned.
>> - * XEN_GUEST_HANDLE_PARAM represent a guest pointer, when passed as an
>> + * XEN_GUEST_HANDLE_PARAM represents a guest pointer, when passed as an
>>   * hypercall argument. It is 4 bytes on aarch and 8 bytes on aarch64.
> 
> Is there a "32" missing in this last sentence do you think? (not the bit
> you touched)

I think yes. Could you fix it when you will commit the patch?

> I can fix the "unnecessary" on commit, so:
> Acked-by: Ian Campbell <ian.campbell@citrix.com>

Thanks,

-- 
Julien Grall

Re: [PATCH] xen/arm: Update documentation in the public header arch-arm.h

[Ian Campbell]

On Thu, 2015-01-15 at 13:53 +0000, Julien Grall wrote:
> Hi,
> 
> On 15/01/15 13:48, Ian Campbell wrote:
> > On Wed, 2015-01-14 at 12:53 +0000, Julien Grall wrote:
> >> Minor updates to the documentation in xen/include/public/arch-arm.h:
> >>     - Comments coding style fix
> >>     - Typoes
> >>     - Update the list of supported hypercalls by ARM
> >>     - Remove uncessary comment about 64bit.
> > 
> > "unnecessary"
> > 
> >> Signed-off-by: Julien Grall <julien.grall@linaro.org>
> >> Cc: Ian Jackson <ian.jackson@eu.citrix.com>
> >> Cc: Jan Beulich <jbeulich@suse.com>
> >> Cc: Keir Fraser <keir@xen.org>
> >>
> >> ---
> >>     I'm not sure if we usually backport documentation. If so, I'd like
> >>     to request backporting for Xen 4.5.
> > 
> > I don't think we need to TBH, any development should be against unstable
> > and we publish these headers online for ease of access.
> 
> Ok. I'm fine with that.
> 
> >> + *   All generic sub-operations
> >>   *
> >>   *  HYPERVISOR_domctl
> >>   *   All generic sub-operations, with the exception of:
> >> - *    * XEN_DOMCTL_iomem_permission (not yet implemented)
> >>   *    * XEN_DOMCTL_irq_permission (not yet implemented)
> >>   *
> >>   *  HYPERVISOR_sched_op
> >> @@ -183,7 +178,7 @@
> >>   * XEN_GUEST_HANDLE represents a guest pointer, when passed as a field
> >>   * in a struct in memory. On ARM is always 8 bytes sizes and 8 bytes
> >>   * aligned.
> >> - * XEN_GUEST_HANDLE_PARAM represent a guest pointer, when passed as an
> >> + * XEN_GUEST_HANDLE_PARAM represents a guest pointer, when passed as an
> >>   * hypercall argument. It is 4 bytes on aarch and 8 bytes on aarch64.
> > 
> > Is there a "32" missing in this last sentence do you think? (not the bit
> > you touched)
> 
> I think yes. Could you fix it when you will commit the patch?

Sure. I'll apply it now.

> 
> > I can fix the "unnecessary" on commit, so:
> > Acked-by: Ian Campbell <ian.campbell@citrix.com>
> 
> Thanks,
>