feat(doc): add guest configuration to bao-classic config documentation #78

Diogo21Costa · 2023-12-07T18:09:59Z

PR Description

In this pull request, I'm adding content to the "Guest Configuration" section of the config documentation for the Bao hypervisor.

Guest Image Configuration
VM Configuration (Virtual Platform)
CPU Affinity (Mapping of Virtual to Physical CPUs)
Cache Coloring Setup

The focus here is to provide a comprehensive description for each field, offering detailed insights into their functionalities.

Do you have any suggestions or feedback concerning the content provided in the "Guest Configuration" section?

Signed-off-by: Diogo21Costa <[email protected]>

Signed-off-by: Diogo Costa <[email protected]>

josecm · 2023-12-07T18:38:13Z

I think @DavidMCerdeira should also participate in these reviews...

josecm

I think we need a few iterations on this one. And possibly discuss an alternative structure where we go into details and have text explaining the features and functionalities, while here we only go field by field as you did.

josecm · 2023-12-07T18:18:39Z

source/bao_hyp/img/cpu-affinity.svg

The cpu affinities in the image are wrong. For example, it should be 0x1 or 0b0001 for VM 0.

Thanks, fixed in bae0e3311ec85b598de114a3e05260ba4d109151.

josecm · 2023-12-07T18:20:55Z

source/bao_hyp/config.rst

+    :name: guest-config-fig
+
+
+The configuration of different guests is done by populating a struct called *vmconfig*, as follows:


Maybe here we could add a reference the vmlist referenced in the first part of the document, saying that each entry in that list is a vm_config struct...

Thanks, fixed in 923bbca5719fda58025bfc192b7461efa1d1a1c4.

josecm · 2023-12-07T18:22:08Z

source/bao_hyp/config.rst

+.. code-block:: c
+
+    struct vm_config {
+        struct image;


This is not correct. I know that the structure used for the image is an anonymous structure, but maybe we can change this is to:

Suggested change

struct image;

struct vm_image image;

(both here and in the code)

Thanks, fixed in fadc7a2bb90adc5f6d6fd4eebad36337f2748c39.

josecm · 2023-12-07T18:29:11Z

source/bao_hyp/config.rst

+- **load_addr** [mandatory] - corresponds to the ``image`` load address in the hypervisor address
+  space. This value can be defined using the macro VM_IMAGE_OFFSET(img_name);


Suggested change

- **load_addr** [mandatory] - corresponds to the ``image`` load address in the hypervisor address

space. This value can be defined using the macro VM_IMAGE_OFFSET(img_name);

- **load_addr** [mandatory] - corresponds to the ``image`` load address in physical memory/physical address space. This value can be defined using the macro VM_IMAGE_OFFSET(img_name);

Also, we need to explain that, if separately loaded is set to false, the hypervisor initially interprets this as the offset of the builtin image guest in its own image (hence, VM_IMAGE_OFFSET). At runtime, it fixes the value to be later interpreted as a physical address, by adding to it the address the hypervisor was loaded.

Thanks, fixed in 4b057cd.

josecm · 2023-12-07T18:35:51Z

source/bao_hyp/config.rst

+- **size** [mandatory] - corresponds to the image size. This value can be defined using the macro
+  VM_IMAGE_SIZE(img_name);


Suggested change

- **size** [mandatory] - corresponds to the image size. This value can be defined using the macro

VM_IMAGE_SIZE(img_name);

- **size** [mandatory] - corresponds to the image size. For builtin images declared using `VM_IMAGE`, this value can be defined using the macro VM_IMAGE_SIZE(img_name);

Thanks, fixed in dde0f11fddf139eee0aa33223d587b912c60aecd.

josecm · 2023-12-14T21:02:52Z

source/bao_hyp/config.rst

+- **base**  [mandatory] - corresponds to the virtual base address of the IPC memory region;
+- **size** [mandatory] - corresponds to the size of the IPC memory region;


Again, it is mandatory for base and size to be aligned to the architecture's smallest page size: in all architectures 4K for MMU systems and 64 bytes for MPU.

Thanls, fixed in 404de5a.

josecm · 2023-12-14T21:04:09Z

source/bao_hyp/config.rst

 3. Inter-Process Communication (IPC)
 ####################################
+.. _Inter-Process Communication (IPC):


We need to explain somewhere how the IPC works 🤔

Agree, included new content in 854fe14.

josecm · 2023-12-14T21:05:22Z

source/bao_hyp/config.rst

+- **va** [mandatory] - corresponds to the base virtual address of the device;
+- **size** [mandatory] - corresponds to the size of the device memory region;


Again, explain that it is mandatory for base and size to be aligned to the architecture's smallest page size: in all architectures 4K for MMU systems and 64 bytes for MPU.

Thanks, addressed in ae5a5bd.

josecm · 2023-12-14T21:05:54Z

source/bao_hyp/config.rst

+  the VM. By default, ``interrupt_num`` equals to 0;
+- **interrupts** [mandatory if *interrupt_num*>0] - defines a list of interrupt IDs generated by
+  the device - ``(irqid_t[]) {irq_1, ..., irq_n};``
+- **id** [optional] - corresponds to the bus master id for iommu effects:


Which should also add more explanation to this, possibly on a per-platform basis.

josecm · 2023-12-14T21:06:40Z

source/bao_hyp/config.rst

+- **cpu_affinity** [optional] - corresponds to a bitmap signaling the preferred physical CPUs
+  assigned to the VM. If this value is mutually exclusive for all the VMs, the physical CPUs
+  assigned to each VM follow the bitmap. Otherwise (in case of bit overlap or lack of affinity
+  definition), the CPU assignment is defined by the hypervisor;


the cpu affinity will be as best as possible be followed, but it is not guaranteed.

Thanks, added this information!

Signed-off-by: Diogo21Costa <[email protected]>

Signed-off-by: Diogo Costa <[email protected]>

source/bao_hyp/config.rst

Signed-off-by: Diogo Costa <[email protected]>

Signed-off-by: Diogo21Costa <[email protected]>

source/bao_hyp/config.rst

Signed-off-by: Diogo Costa <[email protected]>

source/bao_hyp/config.rst

Signed-off-by: Diogo Costa <[email protected]>

DavidMCerdeira

Looks good to me.
Only thing missing is re-writing the history which should be done after addressing all pending conversations

danielRep

Apart from minor issues easily solved, it looks very good to me! Great work Diogo.

source/bao_hyp/config.rst

Signed-off-by: Diogo Costa <[email protected]>

DavidMCerdeira · 2024-10-04T10:30:48Z

source/bao_hyp/config.rst


-6. Architectural-Specific Configurations
+.. note::


Add a second note that we shouldn't add the gic to these devices.
A scenario would be where we want to give a large portion of the MMIO, and that MMIO range contains the GIC. In this case we need to split the MMIO range in two creating a hole for the gic.

Thank you for the review @DavidMCerdeira! Addressed this point in this commit

Signed-off-by: Diogo Costa <[email protected]>

DavidMCerdeira · 2024-12-05T16:39:08Z

source/bao_hyp/config.rst

+   When mapping MMIO regions for guests, the memory regions associated with the GIC (Generic
+   Interrupt Controller) must be excluded. Mapping these regions can lead to conflicts or incorrect
+   behavior, as they are typically managed by Bao through trap-and-emulate mechanisms.


When mapping MMIO regions for guests, the memory regions associated with the interrupt controller (only interrupt controllers are target of MMIO trap and emulate in Bao) must be excluded. Mapping these regions can lead to conflicts or incorrect
behavior, as they are typically managed by Bao through trap-and-emulate mechanisms.

Diogo21Costa requested review from danielRep, josecm and miguelafsilva5 as code owners December 7, 2023 18:10

Diogo21Costa changed the title ~~Feat/bao classic config guests~~ feat(doc): add guest configuration to bao-classic config documentation Dec 7, 2023

danielRep self-assigned this Dec 7, 2023

Diogo21Costa added 12 commits December 7, 2023 18:29

feat(doc): add guest configuration introduction

746823c

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add guest image configuration

407c8dd

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add VM configuration - introduction

c92f56b

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add VM configuration - number of vCPUs

413b37b

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add VM configuration - memory mapping

b6db67a

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add VM configuration - IPC

da5b673

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add VM configuration - devices

b78ee89

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add VM configuration - memory management

c22ba39

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add VM configuration - architectural-specific configurations

3d43ffb

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add cpu affinity

1300f5a

Signed-off-by: Diogo21Costa <[email protected]>

feat(doc): add cache coloring

7415b8d

Signed-off-by: Diogo21Costa <[email protected]>

fix(doc): include format tweaks to use the new column limit of 100

77c4429

Signed-off-by: Diogo Costa <[email protected]>

Diogo21Costa force-pushed the feat/bao-classic_config_guests branch from f80f24e to 77c4429 Compare December 7, 2023 18:29

josecm requested a review from DavidMCerdeira December 7, 2023 18:38

josecm requested changes Dec 14, 2023

View reviewed changes

Diogo21Costa added 9 commits January 5, 2024 14:12

fix(img): update cpu-affinity

223e053

Signed-off-by: Diogo21Costa <[email protected]>

fix(heading): update section naming

b5096f0

Signed-off-by: Diogo21Costa <[email protected]>

fix(vm_config): fix introduction text

88b3e28

Signed-off-by: Diogo21Costa <[email protected]>

fix(vm_config): update vm entry description

fedaf73

Signed-off-by: Diogo21Costa <[email protected]>

fix(vm_config): fix struct vm_image declaration

9d82a52

Signed-off-by: Diogo21Costa <[email protected]>

fix(guest_image): update size field description

8e218ad

Signed-off-by: Diogo21Costa <[email protected]>

fix(typo): improve Virtual Machine Configuration section

4af39fd

Signed-off-by: Diogo Costa <[email protected]>

update(doc): refactor Virtual Machine Configuration description

31f18ac

Signed-off-by: Diogo Costa <[email protected]>

update(VM Config): improve struct description

0155757

Signed-off-by: Diogo Costa <[email protected]>

Diogo21Costa added 2 commits September 4, 2024 14:56

fix(doc): update device configuration note

3558ec9

Signed-off-by: Diogo Costa <[email protected]>

fix(doc): remove empty subsection

d2efdcf

Signed-off-by: Diogo Costa <[email protected]>

DavidMCerdeira reviewed Sep 4, 2024

View reviewed changes

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

fix(doc): update MPU VA and PA configuration description

a139c99

Signed-off-by: Diogo Costa <[email protected]>

DavidMCerdeira self-requested a review September 4, 2024 15:41

DavidMCerdeira previously approved these changes Sep 4, 2024

View reviewed changes

danielRep previously approved these changes Sep 4, 2024

View reviewed changes

feat(doc): add shared memory configuration

8b6eb3b

Signed-off-by: Diogo21Costa <[email protected]>

Diogo21Costa dismissed stale reviews from danielRep and DavidMCerdeira via 8b6eb3b September 6, 2024 16:09

DavidMCerdeira requested changes Sep 9, 2024

View reviewed changes

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

Diogo21Costa added 4 commits September 17, 2024 14:16

fix(doc): improve shared memory documentation

33652e5

Signed-off-by: Diogo Costa <[email protected]>

fix(doc): improve shared memory documentation

b4d14d8

Signed-off-by: Diogo Costa <[email protected]>

fix(doc): improve shared memory documentation

f6b8cde

Signed-off-by: Diogo Costa <[email protected]>

fix(doc): improve shared memory documentation

07452d7

Signed-off-by: Diogo Costa <[email protected]>

DavidMCerdeira requested changes Sep 17, 2024

View reviewed changes

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

fix(doc): improve shared memory documentation

3f2a6f1

Signed-off-by: Diogo Costa <[email protected]>

DavidMCerdeira self-requested a review September 17, 2024 14:01

DavidMCerdeira reviewed Sep 17, 2024

View reviewed changes

danielRep reviewed Sep 18, 2024

View reviewed changes

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

source/bao_hyp/config.rst Outdated Show resolved Hide resolved

Diogo21Costa added 4 commits September 19, 2024 09:57

fix(doc): fix guest image documentation

12a303c

Signed-off-by: Diogo Costa <[email protected]>

fix(doc): fix VM config documentation

9ffd91e

Signed-off-by: Diogo Costa <[email protected]>

fix(doc): fix shared memory documentation

9744a25

Signed-off-by: Diogo Costa <[email protected]>

fix(doc): fix devices documentation

b778726

Signed-off-by: Diogo Costa <[email protected]>

danielRep previously approved these changes Sep 19, 2024

View reviewed changes

DavidMCerdeira reviewed Oct 4, 2024

View reviewed changes

fix(doc): add note regarding to MMIO mapping

0c360b5

Signed-off-by: Diogo Costa <[email protected]>

Diogo21Costa dismissed danielRep’s stale review via 0c360b5 December 5, 2024 15:28

DavidMCerdeira self-requested a review December 5, 2024 16:35

DavidMCerdeira requested changes Dec 5, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(doc): add guest configuration to bao-classic config documentation #78

feat(doc): add guest configuration to bao-classic config documentation #78

Diogo21Costa commented Dec 7, 2023

josecm commented Dec 7, 2023

josecm left a comment

josecm Dec 7, 2023

Diogo21Costa Jan 5, 2024

josecm Dec 7, 2023

Diogo21Costa Jan 5, 2024

josecm Dec 7, 2023

Diogo21Costa Jan 5, 2024

josecm Dec 7, 2023

josecm Dec 7, 2023

Diogo21Costa Jan 17, 2024

josecm Dec 7, 2023

Diogo21Costa Jan 5, 2024

josecm Dec 14, 2023

Diogo21Costa Jan 19, 2024

josecm Dec 14, 2023

Diogo21Costa Jan 19, 2024

josecm Dec 14, 2023

Diogo21Costa Jan 19, 2024

josecm Dec 14, 2023

josecm Dec 14, 2023

Diogo21Costa Mar 12, 2024

DavidMCerdeira left a comment

danielRep left a comment

DavidMCerdeira Oct 4, 2024

Diogo21Costa Dec 5, 2024

DavidMCerdeira Dec 5, 2024

		:name: guest-config-fig


		The configuration of different guests is done by populating a struct called vmconfig, as follows:

		- load_addr [mandatory] - corresponds to the ``image`` load address in the hypervisor address
		space. This value can be defined using the macro VM_IMAGE_OFFSET(img_name);

		- size [mandatory] - corresponds to the image size. This value can be defined using the macro
		VM_IMAGE_SIZE(img_name);

		- base [mandatory] - corresponds to the virtual base address of the IPC memory region;
		- size [mandatory] - corresponds to the size of the IPC memory region;

		- va [mandatory] - corresponds to the base virtual address of the device;
		- size [mandatory] - corresponds to the size of the device memory region;

feat(doc): add guest configuration to bao-classic config documentation #78

Are you sure you want to change the base?

feat(doc): add guest configuration to bao-classic config documentation #78

Conversation

Diogo21Costa commented Dec 7, 2023

PR Description

josecm commented Dec 7, 2023

josecm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DavidMCerdeira left a comment

Choose a reason for hiding this comment

danielRep left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment