wip: draft porting guide #81

josecm · 2024-01-19T14:21:12Z

This PR details the steps for porting the Bao Hypervisor to a new platform. Still WIP, but any feedback is welcome.

Diogo21Costa · 2024-02-05T14:40:35Z

source/bao_hyp/user_manual/porting.rst

+The Bao Hypervisor only contains architecture-specific drivers (e.g., interrupt controllers or
+IOMMUS). Therefore porting the hypervisor essentially resumes to two simple operation: creating a
+platform description folder containing a platform definition source and header files which
+indicates, among others, the number of CPUs or the memory available. The exception is an UART driver
+used fore logging, so if a driver is not available for a UART on the target platform this might


In my opinion, the first sentence doesn't contribute significantly. It looks like a bit disconnected from the remaining text.

Suggested change

The Bao Hypervisor only contains architecture-specific drivers (e.g., interrupt controllers or

IOMMUS). Therefore porting the hypervisor essentially resumes to two simple operation: creating a

platform description folder containing a platform definition source and header files which

indicates, among others, the number of CPUs or the memory available. The exception is an UART driver

used fore logging, so if a driver is not available for a UART on the target platform this might

Porting the hypervisor involves two basic steps: (i) creating a platform description folder with

source and header files that specify platform details, such as the number of CPUs or available

memory, and (ii) integrating a UART driver used for logging, so if a driver is not available for a

UART on the target platform this might require writing a custom driver.

Diogo21Costa · 2024-02-05T14:40:36Z

source/bao_hyp/user_manual/porting.rst

+require writing such a driver. Finally, given for some platforms provide a custom mechanism to
+define DMA device Master IDs required for configuring IOMMUs, one might require to configure


At this point, it would be interesting to refer to some examples to contextualize the firmware changes

Diogo21Costa · 2024-02-05T14:41:20Z

source/bao_hyp/user_manual/porting.rst

+Creating a new platform description for the Bao Hypervisor starts by creating a new directory under
+*src/platform*. For example, for port to a *foo* platform, create the directory *src/platform/foo*.


Suggested change

Creating a new platform description for the Bao Hypervisor starts by creating a new directory under

*src/platform*. For example, for port to a *foo* platform, create the directory *src/platform/foo*.

Creating a new platform description for the Bao Hypervisor begins by establishing a new directory

under src/platform. For instance, when porting to a foo platform, generate the directory

src/platform/foo.

Suggested change

Creating a new platform description for the Bao Hypervisor starts by creating a new directory under

*src/platform*. For example, for port to a *foo* platform, create the directory *src/platform/foo*.

Creating a new platform description for the Bao Hypervisor starts by creating a new directory under

``src/platform``. For example, for port to a *foo* platform, create the directory ``src/platform/foo``.

Diogo21Costa · 2024-02-05T14:41:25Z

source/bao_hyp/user_manual/porting.rst

+- **base** [mandatory] - Is the base physical address of that memory region. Must be aligned to the minimum architecture's page size;
+- **size** [mandatory] - The size of the memory region. Must be aligned to the minimum architecture's page size;


Suggested change

- **base** [mandatory] - Is the base physical address of that memory region. Must be aligned to the minimum architecture's page size;

- **size** [mandatory] - The size of the memory region. Must be aligned to the minimum architecture's page size;

- **base** [mandatory] - Is the base physical address of that memory region.

- **size** [mandatory] - The size of the memory region.

.. warning::

Ensure that the memory ``base`` and ``size`` are aligned to the minimum architecture's page size.

Change the format to inline code.

Diogo21Costa · 2024-02-05T14:41:27Z

source/bao_hyp/user_manual/porting.rst

+Note that, by convention, we do not add on-chip/scratcpad SRAMs as a platform memory region as the hypervisor as an uniform view of memory.
+This regions should be assigned to guests in the form of devices.


Suggested change

Note that, by convention, we do not add on-chip/scratcpad SRAMs as a platform memory region as the hypervisor as an uniform view of memory.

This regions should be assigned to guests in the form of devices.

.. note::

By convention, we do not add on-chip/scratcpad SRAMs as a platform memory region as the hypervisor as an uniform view of memory. This regions should be assigned to guests in the form of devices.

danielRep

I don't have any major suggestions to add on the structure of the document. I considerer it already touches all the necessary topics.
Few points:

inline code format must be used be used for file paths, file names, shell commands, programming language directives/keywords/identifiers, syntax characters as required in the Documentation Guidelines;
when using tabs, the contents of each tab must one step indented from the ..tab: directive;
an image from the folder structure of a platform definition would be helpful

danielRep · 2024-02-14T16:42:22Z

source/bao_hyp/user_manual/porting.rst

+1) Create a platform directory containing a platform description [mandatory];
+2) Writing an UART driver [if the driver for the target UART is not available];
+3) Setting up firmware to define DMA device Master IDs used by the platform IOMMU [platform dependent];


@Diogo21Costa suggested to add here reference links to each section on the document detailing each process. I deleted the comment by mistake. I would also change the [] for ()

danielRep · 2024-02-14T16:48:17Z

source/bao_hyp/user_manual/porting.rst

+1) A source file (e.g., *src/platform/foo/foo_desc.c*) containing the platform description structure, `struct platform platform`
+defininition;
+2) A *plat.h* header file under *src/platform/foo/inc/plat/*  with platform-specific includes and definitions;
+3) A *platform.mk* makefile containing definitions required by the build system (e.g., the target architecture);
+4) A *objects.mk* containing the platform's target object files. In principle this should only contain the 
+object for the source description file, but you may add others if you have any other platform specific sources.


Suggested change

1) A source file (e.g., *src/platform/foo/foo_desc.c*) containing the platform description structure, `struct platform platform`

defininition;

2) A *plat.h* header file under *src/platform/foo/inc/plat/* with platform-specific includes and definitions;

3) A *platform.mk* makefile containing definitions required by the build system (e.g., the target architecture);

4) A *objects.mk* containing the platform's target object files. In principle this should only contain the

object for the source description file, but you may add others if you have any other platform specific sources.

1) A source file (e.g., ``src/platform/foo/foo_desc.c``) containing the platform description structure, `struct platform platform`

definition;

2) A ``plat.h`` header file under ``src/platform/foo/inc/plat/`` with platform-specific includes and definitions;

3) A ``platform.mk`` makefile containing definitions required by the build system (e.g., the target architecture);

4) A ``objects.mk`` containing the platform's target object files. In principle this should only contain the

object for the source description file, but you may add others if you have any other platform specific sources.

danielRep · 2024-02-14T16:51:18Z

source/bao_hyp/user_manual/porting.rst

+Creating a new platform description for the Bao Hypervisor starts by creating a new directory under
+*src/platform*. For example, for port to a *foo* platform, create the directory *src/platform/foo*.


Suggested change

Creating a new platform description for the Bao Hypervisor starts by creating a new directory under

*src/platform*. For example, for port to a *foo* platform, create the directory *src/platform/foo*.

Creating a new platform description for the Bao Hypervisor starts by creating a new directory under

``src/platform``. For example, for port to a *foo* platform, create the directory ``src/platform/foo``.

danielRep · 2024-02-14T16:52:32Z

source/bao_hyp/user_manual/porting.rst

+Platform Description Structure
+******************************
+
+A global structure of type `struct platform` named `platform` must be defined when porting Bao to a new platform.


Suggested change

A global structure of type `struct platform` named `platform` must be defined when porting Bao to a new platform.

A global structure of type ``struct platform`` named ``platform`` must be defined when porting Bao to a new platform.

danielRep · 2024-02-14T16:54:45Z

source/bao_hyp/user_manual/porting.rst

+Porting
+=======


Suggested change

Porting

=======

Porting Guide

=============

danielRep · 2024-02-15T11:34:34Z

source/bao_hyp/user_manual/porting.rst

+Architcture-Specific Platform Description
+#########################################


Suggested change

Architcture-Specific Platform Description

#########################################

Architecture-Specific Platform Description

##########################################

danielRep · 2024-02-15T11:38:53Z

source/bao_hyp/user_manual/porting.rst

+
+    .. code-block:: c
+
+        struct arch_platform {
+            struct gic_dscrp {
+                paddr_t gicc_addr;
+                paddr_t gich_addr;
+                paddr_t gicv_addr;
+                paddr_t gicd_addr;
+                paddr_t gicr_addr;
+
+                irqid_t maintenance_id;
+            } gic;
+
+            struct smmu_dscrp {
+                paddr_t base;
+                streamid_t global_mask;
+            } smmu;
+
+            struct clusters {
+                size_t num;
+                size_t* core_num;
+            } clusters;
+        };
+
+    Where, for the GIC interrupt controller `struct gic_dscrp` description:
+
+    - **gic.gicc_addr** [mandatory for GICv2 platforms] - base address for the GIC's CPU Interface;
+    - **gic.gich_addr** [mandatory for GICv2 platforms] - base address for the GIC's Virtual Interface Control Registers;
+    - **gic.gicv_addr** [mandatory for GICv2 platforms] - base address for the GIC's Virtual CPU Interface;
+    - **gic.gicd_addr** [mandatory] - base address for the GIC's Distributor;
+    - **gic.gicr_addr** [mandatory for GICv3/4 platforms] - base address for the GIC's Redistributor;
+    - **gic.maintenance_id** [mandatory] - The interrupt ID for the GIC's maintenance interrupt;
+
+    For the SMMU `struct smmu_dscrp`:
+
+    - **smmu.base** [mandatory] - is the base address for the SMMU;
+    - **smmu.global_mask** [optional; only valid for SMMUv2] - a mask to be applied to all SMMUv2's Stream Match Registers;
+
+
+    Finally, when CPUs are organized in clusters, in the Arm architecture their IDs are assigned using an hierarchical schema.
+    To be able to calculate the linearized ID for each core, we require the port to provide the number of CPUs of cluster in
+    ascending order of AFF1.
+


This needs an extra indentation to be grouped on each tab. Same for the RISC-V information.

danielRep · 2024-02-15T11:40:09Z

source/bao_hyp/user_manual/porting.rst

+
+    For the SMMU `struct smmu_dscrp`:
+
+    - **smmu.base** [mandatory] - is the base address for the SMMU;
+    - **smmu.global_mask** [optional; only valid for SMMUv2] - a mask to be applied to all SMMUv2's Stream Match Registers;
+


Use inline code format for all code related text.

danielRep · 2024-02-15T11:45:46Z

source/bao_hyp/user_manual/porting.rst

+    - **gic.gicd_addr** [mandatory] - base address for the GIC's Distributor;
+    - **gic.gicr_addr** [mandatory for GICv3/4 platforms] - base address for the GIC's Redistributor;
+    - **gic.maintenance_id** [mandatory] - The interrupt ID for the GIC's maintenance interrupt;
+


I would split this for each GIC version to be more explicit.

For all platforms: - **gic.maintenance_id** - **gic.gicd_addr** For GICv2 platforms: - **gic.gicc_addr** - **gic.gich_addr** - **gic.gicv_addr** For GICv3/4 platforms: - **gic.gicr_addr**

danielRep · 2024-02-15T11:47:20Z

source/bao_hyp/user_manual/porting.rst

+Platform Make Defintions
+************************


Suggested change

Platform Make Defintions

************************

Platform Make Definitions

*************************

Signed-off-by: Jose Martins <josemartins90@gmail.com>

DavidMCerdeira · 2024-09-04T10:20:16Z

source/bao_hyp/user_manual/porting.rst

+.. tabs::
+    .. tab:: Arm
+
+    - `GIC_VERSION` [mandatory] - indicates the GIC's version present on the platform. Option: `GICV2`, or `GICV3`.
+
+    .. tab:: RISC-V
+
+    - `IRQC` [mandatory] - indicates the interrupt controller available on the platform. Options: `PLIC`, `APLIC`, or `AIA`.
+


Currently not working

DavidMCerdeira · 2024-09-04T10:21:51Z

source/bao_hyp/user_manual/porting.rst

+1) Create a platform directory containing a platform description [mandatory];
+2) Writing an UART driver [if the driver for the target UART is not available];
+3) Setting up firmware to define DMA device Master IDs used by the platform IOMMU [platform dependent];


DavidMCerdeira · 2024-09-04T10:22:23Z

source/bao_hyp/user_manual/porting.rst

+1) A source file (e.g., *src/platform/foo/foo_desc.c*) containing the platform description structure, `struct platform platform`
+defininition;
+2) A *plat.h* header file under *src/platform/foo/inc/plat/*  with platform-specific includes and definitions;
+3) A *platform.mk* makefile containing definitions required by the build system (e.g., the target architecture);
+4) A *objects.mk* containing the platform's target object files. In principle this should only contain the 
+object for the source description file, but you may add others if you have any other platform specific sources.


List is not working

DavidMCerdeira · 2024-09-04T10:25:19Z

source/bao_hyp/user_manual/porting.rst

+
+The architecture-specific field of the platform description includes fields that describe interrupt controllers or others. 
+
+.. tabs::


Tabs not working

Diogo21Costa self-requested a review January 29, 2024 16:32

Diogo21Costa reviewed Feb 5, 2024

View reviewed changes

danielRep self-assigned this Feb 14, 2024

bao-project deleted a comment from Diogo21Costa Feb 14, 2024

danielRep requested changes Feb 15, 2024

View reviewed changes

wip: draft porting guide

74ce71e

Signed-off-by: Jose Martins <josemartins90@gmail.com>

danielRep force-pushed the wip/porting_guide branch from 1f61406 to 74ce71e Compare March 27, 2024 11:46

DavidMCerdeira force-pushed the main branch 5 times, most recently from 1654e31 to d42b0fa Compare August 26, 2024 10:38

DavidMCerdeira requested changes Sep 4, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

wip: draft porting guide #81

wip: draft porting guide #81

josecm commented Jan 19, 2024

Diogo21Costa Feb 5, 2024

Diogo21Costa Feb 5, 2024

Diogo21Costa Feb 5, 2024

danielRep Feb 14, 2024

Diogo21Costa Feb 5, 2024

danielRep Feb 14, 2024

Diogo21Costa Feb 5, 2024

danielRep left a comment

danielRep Feb 14, 2024

DavidMCerdeira Sep 4, 2024

danielRep Feb 14, 2024

danielRep Feb 14, 2024

danielRep Feb 14, 2024

danielRep Feb 14, 2024

danielRep Feb 15, 2024

danielRep Feb 15, 2024

danielRep Feb 15, 2024

danielRep Feb 15, 2024

danielRep Feb 15, 2024

DavidMCerdeira Sep 4, 2024

DavidMCerdeira Sep 4, 2024

DavidMCerdeira Sep 4, 2024

DavidMCerdeira Sep 4, 2024

		require writing such a driver. Finally, given for some platforms provide a custom mechanism to
		define DMA device Master IDs required for configuring IOMMUs, one might require to configure

		Creating a new platform description for the Bao Hypervisor starts by creating a new directory under
		src/platform. For example, for port to a foo platform, create the directory src/platform/foo.

-Creating a new platform description for the Bao Hypervisor starts by creating a new directory under
-*src/platform*. For example, for port to a *foo* platform, create the directory *src/platform/foo*.
+Creating a new platform description for the Bao Hypervisor begins by establishing a new directory
+under src/platform. For instance, when porting to a foo platform, generate the directory
+src/platform/foo.

		- base [mandatory] - Is the base physical address of that memory region. Must be aligned to the minimum architecture's page size;
		- size [mandatory] - The size of the memory region. Must be aligned to the minimum architecture's page size;

		Note that, by convention, we do not add on-chip/scratcpad SRAMs as a platform memory region as the hypervisor as an uniform view of memory.
		This regions should be assigned to guests in the form of devices.

	A global structure of type `struct platform` named `platform` must be defined when porting Bao to a new platform.
	A global structure of type ``struct platform`` named ``platform`` must be defined when porting Bao to a new platform.

-Porting
-=======
+Porting Guide
+=============

		Architcture-Specific Platform Description
		#########################################


		The architecture-specific field of the platform description includes fields that describe interrupt controllers or others.

		.. tabs::

wip: draft porting guide #81

Are you sure you want to change the base?

wip: draft porting guide #81

Conversation

josecm commented Jan 19, 2024

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

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

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