Re: [PATCH 33/36] doc, xen-command-line: introduce coloring options

[Jan Beulich <jbeulich@xxxxxxxx>]

On 04.03.2022 18:46, Marco Solieri wrote:
> From: Luca Miccio <lucmiccio@xxxxxxxxx>
> 
> Four additional parameters in the Xen command line are used to define
> the underlying coloring policy, which is not directly configurable
> otherwise.
> 
> Signed-off-by: Luca Miccio <lucmiccio@xxxxxxxxx>
> Signed-off-by: Marco Solieri <marco.solieri@xxxxxxxxxxxxxxx>
> ---
>  docs/misc/xen-command-line.pandoc | 51 +++++++++++++++++++++++++++++--
>  1 file changed, 49 insertions(+), 2 deletions(-)

Documentation of new command line options should be added in the same
patch which adds support for the options.

> diff --git a/docs/misc/xen-command-line.pandoc 
> b/docs/misc/xen-command-line.pandoc
> index efda335652..a472d51cf9 100644
> --- a/docs/misc/xen-command-line.pandoc
> +++ b/docs/misc/xen-command-line.pandoc
> @@ -299,6 +299,20 @@ can be maintained with the pv-shim mechanism.
>      cause Xen not to use Indirect Branch Tracking even when support is
>      available in hardware.
>  
> +### buddy\_size (arm64)

In new options we generally prefer - over _. I also don't think the name
is making clear enough what is actually being controlled.

Jan

> +> `= <size in megabyte>`
> +
> +> Default: `64 MB`
> +
> +Amount of memory reserved for the buddy allocator when colored allocator is
> +active. This options is useful only if coloring support is enabled.
> +The colored allocator is meant as an alternative to the buddy allocator,
> +since its allocation policy is by definition incompatible with the
> +generic one. Since the Xen heap systems is not colored yet, we need to
> +support the coexistence of the two allocators for now. This parameter, which 
> is
> +optional and for expert only, is used to set the amount of memory reserved to
> +the buddy allocator.
> +
>  ### clocksource (x86)
>  > `= pit | hpet | acpi | tsc`
>  
> @@ -884,7 +898,17 @@ Controls for the dom0 IOMMU setup.
>  
>      Incorrect use of this option may result in a malfunctioning system.
>  
> -### dom0_ioports_disable (x86)
> +### dom0\_colors (arm64)
> +> `= List of <integer>-<integer>`
> +
> +> Default: `All available colors`
> +
> +Specify dom0 color configuration. If the parameter is not set, all available
> +colors are chosen and the user is warned on Xen's serial console. This color
> +configuration acts also as the default one for all DomUs that do not have any
> +explicit color assignment in their configuration file.
> +
> +### dom0\_ioports\_disable (x86)
>  > `= List of <hex>-<hex>`
>  
>  Specify a list of IO ports to be excluded from dom0 access.
> @@ -2625,6 +2649,20 @@ unknown NMIs will still be processed.
>  Set the NMI watchdog timeout in seconds.  Specifying `0` will turn off
>  the watchdog.
>  
> +### way\_size (arm64)
> +> `= <size in byte>`
> +
> +> Default: `Obtained from the hardware`
> +
> +Specify the way size of the Last Level Cache. This parameter is only useful 
> with
> +coloring support enabled. It is an optional, expert-only parameter and it is
> +used to calculate what bits in the physical address can be used by the 
> coloring
> +algorithm, and thus the maximum available colors on the platform. It can be
> +obtained by dividing the total LLC size by the number of associativity ways.
> +By default, the value is also automatically computed during coloring
> +initialization to avoid any kind of misconfiguration. For this reason, it is
> +highly recommended to use this boot argument with specific needs only.
> +
>  ### x2apic (x86)
>  > `= <boolean>`
>  
> @@ -2642,7 +2680,16 @@ In the case that x2apic is in use, this option 
> switches between physical and
>  clustered mode.  The default, given no hint from the **FADT**, is cluster
>  mode.
>  
> -### xenheap_megabytes (arm32)
> +### xen\_colors (arm64)
> +> `= List of <integer>-<integer>`
> +
> +> Default: `0-0: the lowermost color`
> +
> +Specify Xen color configuration. 
> +Two colors are most likely needed on platforms where private caches are
> +physically indexed, e.g. the L1 instruction cache of the Arm Cortex-A57.
> +
> +### xenheap\_megabytes (arm32)
>  > `= <size>`
>  
>  > Default: `0` (1/32 of RAM)