[PATCH v4] Documentation to various header files (v4?).

[PATCH v4] Documentation to various header files (v4?).

[Konrad Rzeszutek Wilk]

Hey Ian,

I think this is the last posting of these? I believe we are just
waiting for Jan to Ack the:

 [PATCH 5/6] docs: Document start_info changes in Xen 4.2.

and otherwise they are ready to go?

 xen/include/public/elfnote.h    |  6 ++++++
 xen/include/public/features.h   | 14 ++++++++++++++
 xen/include/public/io/xs_wire.h |  5 ++++-
 xen/include/public/xen.h        | 22 ++++++++++++++++++++--
 4 files changed, 44 insertions(+), 3 deletions(-)

Konrad Rzeszutek Wilk (6):
      docs: Document the ELF_FEATURES entry
      docs: Add some extra details to the ELF note.
      docs: Document the shared structure.
      docs: Document the dom0_vga_console_info structure.
      docs: Document start_info changes in Xen 4.2.
      docs: Document the XenBus structure.

[PATCH 1/6] docs: Document the ELF_FEATURES entry

[Konrad Rzeszutek Wilk]

Mark-up for inclusion of generated docs.

Acked-by: Ian Campbell <ian.campbell@citrix.com>
Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 xen/include/public/features.h | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/xen/include/public/features.h b/xen/include/public/features.h
index 5b70418..a149aa6 100644
--- a/xen/include/public/features.h
+++ b/xen/include/public/features.h
@@ -28,6 +28,20 @@
 #define __XEN_PUBLIC_FEATURES_H__
 
 /*
+ * `incontents 200 elfnotes_features XEN_ELFNOTE_FEATURES
+ *
+ * The list of all the features the guest supports. They are set by
+ * parsing the XEN_ELFNOTE_FEATURES and XEN_ELFNOTE_SUPPORTED_FEATURES
+ * string. The format is the  feature names (as given here without the
+ * "XENFEAT_" prefix) separated by '|' characters.
+ * If a feature is required for the kernel to function then the feature name
+ * must be preceded by a '!' character.
+ *
+ * Note that if XEN_ELFNOTE_SUPPORTED_FEATURES is used, then in the
+ * XENFEAT_dom0 MUST be set if the guest is to be booted as dom0,
+ */
+
+/*
  * If set, the guest does not need to write-protect its pagetables, and can
  * update them via direct writes.
  */
-- 
1.8.0.2

[PATCH 2/6] docs: Add some extra details to the ELF note.

[Konrad Rzeszutek Wilk]

Such as how the string values MUST be NULL terminated ASCII.

Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 xen/include/public/elfnote.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/xen/include/public/elfnote.h b/xen/include/public/elfnote.h
index b7e4574..8566a7e 100644
--- a/xen/include/public/elfnote.h
+++ b/xen/include/public/elfnote.h
@@ -38,6 +38,9 @@
  *
  * LEGACY indicated the fields in the legacy __xen_guest string which
  * this a note type replaces.
+ *
+ * String values (for non-legacy) are NULL terminated ASCII, also known
+ * as ASCIZ type.
  */
 
 /*
@@ -160,6 +163,9 @@
 
 /*
  * Whether or not the guest supports cooperative suspend cancellation.
+ * This is a numeric value.
+ *
+ * Default is 0
  */
 #define XEN_ELFNOTE_SUSPEND_CANCEL 14
 
-- 
1.8.0.2

[PATCH 3/6] docs: Document the shared structure.

[Konrad Rzeszutek Wilk]

Mark-up for inclusion of generated docs.

Acked-by: Ian Campbell <ian.campbell@citrix.com>
Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 xen/include/public/xen.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index e9431e2..1091229 100644
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -622,6 +622,7 @@ typedef struct vcpu_info vcpu_info_t;
 #endif
 
 /*
+ * `incontents 200 startofday_shared Start-of-day shared data structure
  * Xen/kernel shared data -- pointer provided in start_info.
  *
  * This structure is defined to be both smaller than a page, and the
-- 
1.8.0.2

[PATCH 4/6] docs: Document the dom0_vga_console_info structure.

[Konrad Rzeszutek Wilk]

Mark-up for inclusion of generated docs.

[v2: s/dom9/dom0/]
Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 xen/include/public/xen.h | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index 1091229..73fd7e7 100644
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -779,7 +779,14 @@ struct xen_multiboot_mod_list
     /* Unused, must be zero */
     uint32_t pad;
 };
-
+/*
+ * `incontents 200 startofday_dom0_console Dom0_console
+ *
+ * The console structure in start_info.console.dom0
+ *
+ * This structure includes a variety of information required to
+ * have a working VGA/VESA console.
+ */
 typedef struct dom0_vga_console_info {
     uint8_t video_type; /* DOM0_VGA_CONSOLE_??? */
 #define XEN_VGATYPE_TEXT_MODE_3 0x03
-- 
1.8.0.2

[PATCH 5/6] docs: Document start_info changes in Xen 4.2.

[Konrad Rzeszutek Wilk]

The  25833:bb85bbccb1c9. "x86/32-on-64: adjust Dom0 initial page table layout"
fixes a bug in the reported value of pt_base versus where the page tables
actually start. This documents this in the start of the world header note.

This clarifies the implied understanding that the page table space is
pointed by pt_base. As in it is ".. implied that the range of page-tables
is the range [pt_base, pt_base + nr_pt_frames), whereas that that range
here indeed is [pt_base - 2, pt_base -2 + nr_pt_frames)" (Jan Beulich).

Also make it crystal clear that pt_base == %cr3.

Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 xen/include/public/xen.h | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index 73fd7e7..4dd9615 100644
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -693,7 +693,7 @@ typedef struct shared_info shared_info_t;
  *      c. list of allocated page frames [mfn_list, nr_pages]
  *         (unless relocated due to XEN_ELFNOTE_INIT_P2M)
  *      d. start_info_t structure        [register ESI (x86)]
- *      e. bootstrap page tables         [pt_base, CR3 (x86)]
+ *      e. bootstrap page tables         [pt_base and CR3 (x86)]
  *      f. bootstrap stack               [register ESP (x86)]
  *  4. Bootstrap elements are packed together, but each is 4kB-aligned.
  *  5. The initial ram disk may be omitted.
@@ -705,6 +705,16 @@ typedef struct shared_info shared_info_t;
  *  8. There is guaranteed to be at least 512kB padding after the final
  *     bootstrap element. If necessary, the bootstrap virtual region is
  *     extended by an extra 4MB to ensure this.
+ *
+ * Note: Prior to 25833:bb85bbccb1c9. ("x86/32-on-64 adjust Dom0 initial page
+ * table layout") a bug caused the pt_base (3.e above) and cr3 to not point
+ * to the start of the guest page tables (it was offset by two pages).
+ * This only manifested itself on 32-on-64 dom0 kernels and not 32-on-64 domU
+ * or 64-bit kernels of any colour. The page tables for a 32-on-64 dom0 got
+ * allocated in the order: 'first L1','first L2', 'first L3', so the offset
+ * to the page table base is by two pages back. The initial domain if it is
+ * 32-bit and runs under a 64-bit hypervisor should _NOT_ use two of the
+ * pages preceding pt_base and mark them as reserved/unused.
  */
 
 #define MAX_GUEST_CMDLINE 1024
-- 
1.8.0.2

[PATCH 6/6] docs: Document the XenBus structure.

[Konrad Rzeszutek Wilk]

Mark-up for inclusion of generated docs.

Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 xen/include/public/io/xs_wire.h | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/xen/include/public/io/xs_wire.h b/xen/include/public/io/xs_wire.h
index 36ff33c..99d24e3 100644
--- a/xen/include/public/io/xs_wire.h
+++ b/xen/include/public/io/xs_wire.h
@@ -103,7 +103,10 @@ enum xs_watch_type
     XS_WATCH_TOKEN
 };
 
-/* Inter-domain shared memory communications. */
+/*
+ * `incontents 150 xenstore_struct XenStore wire protocol.
+ *
+ * Inter-domain shared memory communications. */
 #define XENSTORE_RING_SIZE 1024
 typedef uint32_t XENSTORE_RING_IDX;
 #define MASK_XENSTORE_IDX(idx) ((idx) & (XENSTORE_RING_SIZE-1))
-- 
1.8.0.2

Re: [PATCH v4] Documentation to various header files (v4?).

[Ian Campbell]

On Fri, 2013-03-15 at 19:51 +0000, Konrad Rzeszutek Wilk wrote:
> Hey Ian,
> 
> I think this is the last posting of these? I believe we are just
> waiting for Jan to Ack the:
> 
>  [PATCH 5/6] docs: Document start_info changes in Xen 4.2.
> 
> and otherwise they are ready to go?

I think so too.

Did you CC Jan?

> 
>  xen/include/public/elfnote.h    |  6 ++++++
>  xen/include/public/features.h   | 14 ++++++++++++++
>  xen/include/public/io/xs_wire.h |  5 ++++-
>  xen/include/public/xen.h        | 22 ++++++++++++++++++++--
>  4 files changed, 44 insertions(+), 3 deletions(-)
> 
> Konrad Rzeszutek Wilk (6):
>       docs: Document the ELF_FEATURES entry
>       docs: Add some extra details to the ELF note.
>       docs: Document the shared structure.
>       docs: Document the dom0_vga_console_info structure.
>       docs: Document start_info changes in Xen 4.2.
>       docs: Document the XenBus structure.
> 

Re: [PATCH 5/6] docs: Document start_info changes in Xen 4.2.

[Jan Beulich]

>>> On 15.03.13 at 20:51, Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> wrote:
> The  25833:bb85bbccb1c9. "x86/32-on-64: adjust Dom0 initial page table layout"
> fixes a bug in the reported value of pt_base versus where the page tables
> actually start. This documents this in the start of the world header note.
> 
> This clarifies the implied understanding that the page table space is
> pointed by pt_base. As in it is ".. implied that the range of page-tables
> is the range [pt_base, pt_base + nr_pt_frames), whereas that that range
> here indeed is [pt_base - 2, pt_base -2 + nr_pt_frames)" (Jan Beulich).
> 
> Also make it crystal clear that pt_base == %cr3.

Question is - do we really want this? While I provided aforementioned
fix, I was never really convinced whether it was the hypervisor or
the kernel that misbehaved here. It just was so that dealing with this
on the hypervisor side was much easier.

Perhaps Keir would remember what the original intentions (if any)
were regarding the page table layout (i.e. whether the above
equality was really intended).

Jan

> Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
> ---
>  xen/include/public/xen.h | 12 +++++++++++-
>  1 file changed, 11 insertions(+), 1 deletion(-)
> 
> diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
> index 73fd7e7..4dd9615 100644
> --- a/xen/include/public/xen.h
> +++ b/xen/include/public/xen.h
> @@ -693,7 +693,7 @@ typedef struct shared_info shared_info_t;
>   *      c. list of allocated page frames [mfn_list, nr_pages]
>   *         (unless relocated due to XEN_ELFNOTE_INIT_P2M)
>   *      d. start_info_t structure        [register ESI (x86)]
> - *      e. bootstrap page tables         [pt_base, CR3 (x86)]
> + *      e. bootstrap page tables         [pt_base and CR3 (x86)]
>   *      f. bootstrap stack               [register ESP (x86)]
>   *  4. Bootstrap elements are packed together, but each is 4kB-aligned.
>   *  5. The initial ram disk may be omitted.
> @@ -705,6 +705,16 @@ typedef struct shared_info shared_info_t;
>   *  8. There is guaranteed to be at least 512kB padding after the final
>   *     bootstrap element. If necessary, the bootstrap virtual region is
>   *     extended by an extra 4MB to ensure this.
> + *
> + * Note: Prior to 25833:bb85bbccb1c9. ("x86/32-on-64 adjust Dom0 initial page
> + * table layout") a bug caused the pt_base (3.e above) and cr3 to not point
> + * to the start of the guest page tables (it was offset by two pages).
> + * This only manifested itself on 32-on-64 dom0 kernels and not 32-on-64 domU
> + * or 64-bit kernels of any colour. The page tables for a 32-on-64 dom0 got
> + * allocated in the order: 'first L1','first L2', 'first L3', so the offset
> + * to the page table base is by two pages back. The initial domain if it is
> + * 32-bit and runs under a 64-bit hypervisor should _NOT_ use two of the
> + * pages preceding pt_base and mark them as reserved/unused.
>   */
>  
>  #define MAX_GUEST_CMDLINE 1024
> -- 
> 1.8.0.2
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org 
> http://lists.xen.org/xen-devel 

Re: [PATCH 5/6] docs: Document start_info changes in Xen 4.2.

[Keir Fraser]

On 18/03/2013 10:55, "Jan Beulich" <JBeulich@suse.com> wrote:

>>>> On 15.03.13 at 20:51, Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> wrote:
>> The  25833:bb85bbccb1c9. "x86/32-on-64: adjust Dom0 initial page table
>> layout"
>> fixes a bug in the reported value of pt_base versus where the page tables
>> actually start. This documents this in the start of the world header note.
>> 
>> This clarifies the implied understanding that the page table space is
>> pointed by pt_base. As in it is ".. implied that the range of page-tables
>> is the range [pt_base, pt_base + nr_pt_frames), whereas that that range
>> here indeed is [pt_base - 2, pt_base -2 + nr_pt_frames)" (Jan Beulich).
>> 
>> Also make it crystal clear that pt_base == %cr3.
> 
> Question is - do we really want this? While I provided aforementioned
> fix, I was never really convinced whether it was the hypervisor or
> the kernel that misbehaved here. It just was so that dealing with this
> on the hypervisor side was much easier.
> 
> Perhaps Keir would remember what the original intentions (if any)
> were regarding the page table layout (i.e. whether the above
> equality was really intended).

I think I did intend pt_base == cr3 == first page-table page in the
consecutive sequence of reserved pages on domain startup.

 -- Keir

> Jan
> 
>> Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
>> ---
>>  xen/include/public/xen.h | 12 +++++++++++-
>>  1 file changed, 11 insertions(+), 1 deletion(-)
>> 
>> diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
>> index 73fd7e7..4dd9615 100644
>> --- a/xen/include/public/xen.h
>> +++ b/xen/include/public/xen.h
>> @@ -693,7 +693,7 @@ typedef struct shared_info shared_info_t;
>>   *      c. list of allocated page frames [mfn_list, nr_pages]
>>   *         (unless relocated due to XEN_ELFNOTE_INIT_P2M)
>>   *      d. start_info_t structure        [register ESI (x86)]
>> - *      e. bootstrap page tables         [pt_base, CR3 (x86)]
>> + *      e. bootstrap page tables         [pt_base and CR3 (x86)]
>>   *      f. bootstrap stack               [register ESP (x86)]
>>   *  4. Bootstrap elements are packed together, but each is 4kB-aligned.
>>   *  5. The initial ram disk may be omitted.
>> @@ -705,6 +705,16 @@ typedef struct shared_info shared_info_t;
>>   *  8. There is guaranteed to be at least 512kB padding after the final
>>   *     bootstrap element. If necessary, the bootstrap virtual region is
>>   *     extended by an extra 4MB to ensure this.
>> + *
>> + * Note: Prior to 25833:bb85bbccb1c9. ("x86/32-on-64 adjust Dom0 initial
>> page
>> + * table layout") a bug caused the pt_base (3.e above) and cr3 to not point
>> + * to the start of the guest page tables (it was offset by two pages).
>> + * This only manifested itself on 32-on-64 dom0 kernels and not 32-on-64
>> domU
>> + * or 64-bit kernels of any colour. The page tables for a 32-on-64 dom0 got
>> + * allocated in the order: 'first L1','first L2', 'first L3', so the offset
>> + * to the page table base is by two pages back. The initial domain if it is
>> + * 32-bit and runs under a 64-bit hypervisor should _NOT_ use two of the
>> + * pages preceding pt_base and mark them as reserved/unused.
>>   */
>>  
>>  #define MAX_GUEST_CMDLINE 1024
>> -- 
>> 1.8.0.2
>> 
>> 
>> _______________________________________________
>> Xen-devel mailing list
>> Xen-devel@lists.xen.org
>> http://lists.xen.org/xen-devel
> 
> 
> 

Re: [PATCH 5/6] docs: Document start_info changes in Xen 4.2.

[Jan Beulich]

>>> On 18.03.13 at 12:11, Keir Fraser <keir@xen.org> wrote:
> On 18/03/2013 10:55, "Jan Beulich" <JBeulich@suse.com> wrote:
> 
>>>>> On 15.03.13 at 20:51, Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> wrote:
>>> The  25833:bb85bbccb1c9. "x86/32-on-64: adjust Dom0 initial page table
>>> layout"
>>> fixes a bug in the reported value of pt_base versus where the page tables
>>> actually start. This documents this in the start of the world header note.
>>> 
>>> This clarifies the implied understanding that the page table space is
>>> pointed by pt_base. As in it is ".. implied that the range of page-tables
>>> is the range [pt_base, pt_base + nr_pt_frames), whereas that that range
>>> here indeed is [pt_base - 2, pt_base -2 + nr_pt_frames)" (Jan Beulich).
>>> 
>>> Also make it crystal clear that pt_base == %cr3.
>> 
>> Question is - do we really want this? While I provided aforementioned
>> fix, I was never really convinced whether it was the hypervisor or
>> the kernel that misbehaved here. It just was so that dealing with this
>> on the hypervisor side was much easier.
>> 
>> Perhaps Keir would remember what the original intentions (if any)
>> were regarding the page table layout (i.e. whether the above
>> equality was really intended).
> 
> I think I did intend pt_base == cr3 == first page-table page in the
> consecutive sequence of reserved pages on domain startup.

In that case, Konrad, feel free to put my ack on that patch.

Jan