Skip to contentSkip to conversation

docs: fusa: Add dom0less domain configuration requirements

PATCH Superseded Ayan Kumar Halder 3 participants 4 messages Dec 19, 2024 – Jan 8, 2025

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 docs: fusa: Add dom0less domain configuration requirements

From: Michal Orzel <[email protected]>

Add requirements for dom0less domain creation.

---
Changes from -

v1 - 1. As the dom0less domain creation requirements specifies the dt properties for creating domains, it has been moved to product requirements. Product requirements define the interface Xen exposes to other domains.

2. For the requirements which introduces new terms (like grant table, etc), I have provided the definition as part of the comments.

3. Introduced new market requirements to specify that Xen can assign iomem and irqs to domains.

4. The design requirements will be added later.

v2 - 1. Rephrased the requirements as suggested.

2. Split the product requirements into arm64 specific and common.

3. The arm64 specific requirements have arm64_ prefixed to their tag names.

4. Grant table requirements have been dropped for now.

5. Added a market requirement to denote that Xen can support multiple schedulers.

6. Updated index.rst as we have a new file ie product-reqs/reqs.rst.

 docs/fusa/reqs/index.rst                   |   1 +
 docs/fusa/reqs/market-reqs/reqs.rst        |  31 ++++
 docs/fusa/reqs/product-reqs/arm64/reqs.rst | 128 +++++++++++++++-
 docs/fusa/reqs/product-reqs/reqs.rst       | 163 +++++++++++++++++++++
 4 files changed, 321 insertions(+), 2 deletions(-)
 create mode 100644 docs/fusa/reqs/product-reqs/reqs.rst
docs/fusa/reqs/index.rst +1 -0
index 8a4dae6fb2..1088a51d52 100644
@@ -8,6 +8,7 @@ Requirements documentation
 
    intro
    market-reqs/reqs
+   product-reqs/reqs
    product-reqs/arm64/reqs
    design-reqs/arm64/generic-timer
    design-reqs/arm64/sbsa-uart
docs/fusa/reqs/market-reqs/reqs.rst +31 -0
index f456788d96..39b2714237 100644
@@ -47,3 +47,34 @@ Comments:
 
 Needs:
  - XenProd
+
+Static VM definition
+--------------------
+
+`XenMkt~static_vm_definition~1`
+
+Description:
+Xen shall support assigning peripherals to various domains.
+
+Rationale:
+
+Comments:
+Peripheral implies an iomem (input output memory) and/or interrupts.
+
+Needs:
+ - XenProd
+
+Multiple schedulers
+-------------------
+
+`XenMkt~multiple_schedulers~1`
+
+Description:
+Xen shall provide different ways of scheduling virtual cpus onto physical cpus.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/arm64/reqs.rst +126 -2

143 lines not on this page · raw message

docs/fusa/reqs/product-reqs/reqs.rst new file +163 -0

163 lines not on this page · raw message

Signature · 1 line
2.25.1
#1 lore raw

Hi Ayan,

Quoted 193 lines · Ayan Kumar Halder

From: Michal Orzel <[email protected]>

Add requirements for dom0less domain creation.

---
Changes from -

v1 - 1. As the dom0less domain creation requirements specifies the dt properties for creating domains, it has been moved to product requirements. Product requirements define the interface Xen exposes to other domains.

2. For the requirements which introduces new terms (like grant table, etc), I have provided the definition as part of the comments.

3. Introduced new market requirements to specify that Xen can assign iomem and irqs to domains.

4. The design requirements will be added later.

v2 - 1. Rephrased the requirements as suggested.

2. Split the product requirements into arm64 specific and common.

3. The arm64 specific requirements have arm64_ prefixed to their tag names.

4. Grant table requirements have been dropped for now.

5. Added a market requirement to denote that Xen can support multiple schedulers.

6. Updated index.rst as we have a new file ie product-reqs/reqs.rst.

docs/fusa/reqs/index.rst                   |   1 +
docs/fusa/reqs/market-reqs/reqs.rst        |  31 ++++
docs/fusa/reqs/product-reqs/arm64/reqs.rst | 128 +++++++++++++++-
docs/fusa/reqs/product-reqs/reqs.rst       | 163 +++++++++++++++++++++
4 files changed, 321 insertions(+), 2 deletions(-)

create mode 100644 docs/fusa/reqs/product-reqs/reqs.rst

docs/fusa/reqs/index.rst +1 -0
index 8a4dae6fb2..1088a51d52 100644
@@ -8,6 +8,7 @@ Requirements documentation
 
   intro
   market-reqs/reqs
+   product-reqs/reqs
   product-reqs/arm64/reqs
   design-reqs/arm64/generic-timer
   design-reqs/arm64/sbsa-uart
docs/fusa/reqs/market-reqs/reqs.rst +0 -0
index f456788d96..39b2714237 100644
@@ -47,3 +47,34 @@ Comments:
 

Needs:
- XenProd

docs/fusa/reqs/market-reqs/reqs.rst +31 -0
+
+Static VM definition
+--------------------
+
+`XenMkt~static_vm_definition~1`
+
+Description:
+Xen shall support assigning peripherals to various domains.
+
+Rationale:
+
+Comments:
+Peripheral implies an iomem (input output memory) and/or interrupts.
+
+Needs:
+ - XenProd
+
+Multiple schedulers
+-------------------
+
+`XenMkt~multiple_schedulers~1`
+
+Description:
+Xen shall provide different ways of scheduling virtual cpus onto physical cpus.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/arm64/reqs.rst +0 -0
index db91c47a02..c8fee0e49f 100644
@@ -6,7 +6,7 @@ Domain Creation And Runtime

Emulated Timer
--------------

-XenProd~emulated_timer~1
+XenProd~arm64_emulated_timer~1

Description:
Xen shall grant access to "Arm Generic Timer" for the domains.

docs/fusa/reqs/product-reqs/arm64/reqs.rst +0 -0
@@ -25,7 +25,7 @@ Needs:

Emulated UART
-------------

-XenProd~emulated_uart~1
+XenProd~arm64_emulated_uart~1

Description:
Xen shall provide an "Arm SBSA UART" compliant device to the domains.

docs/fusa/reqs/product-reqs/arm64/reqs.rst +0 -0
@@ -40,3 +40,127 @@ Covers:
 

Needs:
- XenSwdgn

docs/fusa/reqs/product-reqs/arm64/reqs.rst +74 -0
+
+Linux kernel image
+------------------
+
+`XenProd~arm64_linux_kernel_image~1`
+
+Description:
+Xen shall create a domain with a binary containing header compliant with Arm64
+Linux kernel image [1].
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+
+Needs:
+ - XenSwdgn
+
+Gzip Linux kernel image
+-----------------------
+
+`XenProd~arm64_linux_kernel_gzip_image~1`
+
+Description:
+Xen shall create a domain with a Gzip compressed binary containing header
+compliant with Arm64 Linux kernel image [1].
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+
+Needs:
+ - XenSwdgn
+
+Kernel with uImage header
+-------------------------
+
+`XenProd~arm64_kernel_uimage~1`
+
+Description:
+Xen shall create a domain with a binary containing uImage header [2].
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+
+Needs:
+ - XenSwdgn
+
+Gzip kernel with uImage header
+------------------------------
+
+`XenProd~arm64_gzip_kernel_uimage~1`
+
+Description:
+Xen shall create a domain with a Gzip compressed binary containing uImage
+header [2].
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+
+Needs:

docs/fusa/reqs/product-reqs/arm64/reqs.rst Covers: · line 126

Quoted 10 lines
docs/fusa/reqs/product-reqs/arm64/reqs.rst +10 -0
+ - XenSwdgn
+
+SPIs
+----
+
+`XenProd~arm64_spis~1`
+
+Description:
+Xen shall create a domain with a number of shared peripheral interrupts as
+specified in the device tree.

"a number" is kind of undefined here. If we have a limit then we should specify it here otherwise this becomes hard to test.
I would suggest to rephrase to "assign hardware shared peripheral interrupts specified in the device tree to a domain"

Quoted 48 lines
docs/fusa/reqs/product-reqs/arm64/reqs.rst +40 -0
+
+Rationale:
+
+Comments:
+Device tree is a data structure and language for describing hardware which is
+readable by an operating system [3].
+A shared peripheral interrupt is a peripheral interrupt that the Arm Generic
+Interrupt Controller's Distributor interface can route to any combination of
+processors [4].
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+ - `XenMkt~static_vm_definition~1`
+
+Needs:
+ - XenSwdgn
+
+Virtual PL011
+-------------
+
+`XenProd~arm64_virtual_pl011~1`
+
+Description:
+Xen shall provide an "Arm PL011 UART" compliant device to the domains.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+ - `XenMkt~provide_console_domains~1`
+
+Needs:
+ - XenSwdgn
+
+| [1] https://github.com/torvalds/linux/blob/master/Documentation/arch/arm64/booting.rst
+| [2] https://source.denx.de/u-boot/u-boot/-/blob/master/include/image.h#L315
+| [3] https://docs.kernel.org/devicetree/usage-model.html
+| [4] https://developer.arm.com/documentation/ihi0048/a/Introduction/Terminology/Interrupt-types?lang=en
docs/fusa/reqs/product-reqs/reqs.rst new file +2 -0
new file mode 100644
index 0000000000..9257fec713
@@ -0,0 +1,163 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+

docs/fusa/reqs/product-reqs/reqs.rst line 12

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+Domain Creation And Runtime
+===========================
+
+Kernel command line arguments
+-----------------------------
+
+`XenProd~kernel_cmd_line_args~1`
+
+Description:
+Xen shall pass kernel command line arguments to a domain via a device tree.

Would it make sense to say where the "command line" to pass is specified ?

Quoted 30 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +30 -0
+
+Rationale:
+
+Comments:
+Device tree is a data structure and language for describing hardware which is
+readable by an operating system [1].
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+
+Needs:
+ - XenSwdgn
+
+Ramdisk
+-------
+
+`XenProd~ramdisk~1`
+
+Description:
+Xen shall provide the address of an initial ramdisk to a domain via a device
+tree.
+
+Rationale:
+
+Comments:
+The initial ramdisk is contained in memory.
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+

docs/fusa/reqs/product-reqs/reqs.rst line 52

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+Needs:
+ - XenSwdgn
+
+Memory
+------
+
+`XenProd~memory~1`
+
+Description:
+Xen shall create a domain with an amount of memory specified in a device tree.

s/an/the/

Quoted 8 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +8 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+

docs/fusa/reqs/product-reqs/reqs.rst line 70

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+Needs:
+ - XenSwdgn
+
+vCPUs
+-----
+
+`XenProd~vcpus~1`
+
+Description:
+A domain shall have a configurable number of virtual CPUs (1 to XX).

XX should be replaced with "the maximum number specified at compilation
in the configuration through CONFIG_MAX_CPUS" or something like that.

Quoted 9 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +9 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+
+Needs:

docs/fusa/reqs/product-reqs/reqs.rst line 89

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+ - XenSwdgn
+
+Credit2 CPU pool scheduler
+--------------------------
+
+`XenProd~credit2_cpu_pool_scheduler~1`
+
+Description:
+Xen shall have a scheduler where a physical cpu can be shared between more than
+one virtual cpu.

i think you can name it in the req: "a credit2 scheduler"

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+ - `XenMkt~multiple_schedulers~1`
+
+Needs:

docs/fusa/reqs/product-reqs/reqs.rst line 109

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+ - XenSwdgn
+
+NUL CPU pool scheduler
+----------------------
+
+`XenProd~nul_cpu_pool_scheduler~1`
+
+Description:
+Xen shall have a scheduler where the virtual cpu will be always running on its
+dedicated physical cpu.

name the scheduler and also "domain virtual cpu is always"

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+
+Rationale:
+
+Comments:
+A NUL CPU pool scheduler maps a virtual cpu to a unique physical cpu.
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+ - `XenMkt~multiple_schedulers~1`
+

docs/fusa/reqs/product-reqs/reqs.rst line 129

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+Needs:
+ - XenSwdgn
+
+Assign iomem
+------------
+
+`XenProd~assign_iomem~1`
+
+Description:
+Xen shall support assigning iomem to a domain.

We cannot assign "any iomem" but pages of iomem (address and size aligned to a page).

docs/fusa/reqs/product-reqs/reqs.rst line 135

Quoted 6 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +6 -0
+
+Rationale:
+
+Comments:
+
+Rationale:

2 times rationale

Quoted 4 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +4 -0
+
+Covers:
+ - `XenMkt~static_vm_definition~1`
+

docs/fusa/reqs/product-reqs/reqs.rst line 149

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+Needs:
+ - XenSwdgn
+
+Forward interrupts
+------------------
+
+`XenProd~forward_irqs~1`
+
+Description:
+Xen shall support forwarding interrupts to a domain.

I think you need to add "hardware interrupts" here.

docs/fusa/reqs/product-reqs/reqs.rst line 155

Quoted 6 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +6 -0
+
+Rationale:
+
+Comments:
+
+Rationale:

rationale twice

Quoted 11 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +8 -0
+
+Covers:
+ - `XenMkt~static_vm_definition~1`
+
+Needs:
+ - XenSwdgn
+
+| [1] https://docs.kernel.org/devicetree/usage-model.html
Signature · 1 line
2.25.1

Cheers
Bertrand

#2 lore raw
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

I just need clarifications on the two points and then I can send v4.

< snip>

Quoted 11 lines

docs/fusa/reqs/product-reqs/reqs.rst line 12

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+Domain Creation And Runtime
+===========================
+
+Kernel command line arguments
+-----------------------------
+
+`XenProd~kernel_cmd_line_args~1`
+
+Description:
+Xen shall pass kernel command line arguments to a domain via a device tree.

Would it make sense to say where the "command line" to pass is specified ?

Yes, although I don't feel very strongly about it. Let me know if this sounds ok :-

Xen shall pass kernel command line arguments to a domain via a device tree using the property "/chosen/xen,xen-bootargs".

< snip>

Quoted 10 lines

docs/fusa/reqs/product-reqs/reqs.rst line 70

Quoted 8 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +8 -0
+
+vCPUs
+-----
+
+`XenProd~vcpus~1`
+
+Description:
+A domain shall have a configurable number of virtual CPUs (1 to XX).

XX should be replaced with "the maximum number specified at compilation
in the configuration through CONFIG_MAX_CPUS" or something like that.

Actually we are talking about virtual CPUS whereas CONFIG_MAX_CPUS refer to physical cpus.

So, it should be GUEST_MAX_VCPUS (which is hardcoded to 128 in xen/include/public/arch-arm.h).

Thus, s/XX/128

I agree with your other comments.

- Ayan

#3 lore raw

Hi Ayan,

Quoted 24 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

I just need clarifications on the two points and then I can send v4.

< snip>

Quoted 11 lines

docs/fusa/reqs/product-reqs/reqs.rst line 12

Quoted 10 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +10 -0
+Domain Creation And Runtime
+===========================
+
+Kernel command line arguments
+-----------------------------
+
+`XenProd~kernel_cmd_line_args~1`
+
+Description:
+Xen shall pass kernel command line arguments to a domain via a device tree.

Would it make sense to say where the "command line" to pass is specified ?

Quoted 4 lines

Yes, although I don't feel very strongly about it. Let me know if this sounds ok :-

Xen shall pass kernel command line arguments to a domain via a device tree using the property "/chosen/xen,xen-bootargs".

In fact those can come from several places (xen command line in the case of dom0, device tree or guest config) so maybe not the simplest to specify it.

Please ignore this comment.

Quoted 14 lines

< snip>

Quoted 10 lines

docs/fusa/reqs/product-reqs/reqs.rst line 70

Quoted 8 lines
docs/fusa/reqs/product-reqs/reqs.rst new file +8 -0
+
+vCPUs
+-----
+
+`XenProd~vcpus~1`
+
+Description:
+A domain shall have a configurable number of virtual CPUs (1 to XX).

XX should be replaced with "the maximum number specified at compilation
in the configuration through CONFIG_MAX_CPUS" or something like that.

Quoted 5 lines

Actually we are talking about virtual CPUS whereas CONFIG_MAX_CPUS refer to physical cpus.

So, it should be GUEST_MAX_VCPUS (which is hardcoded to 128 in xen/include/public/arch-arm.h).

Thus, s/XX/128

Right so you should say 128 here.

Cheers
Bertrand

Quoted 6 lines

I agree with your other comments.

- Ayan