wip: draft porting guide by josecm · Pull Request #81 · bao-project/bao-docs

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

+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.

Addressed in 04edb5e.

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

+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

This will done in later sections.

I think that should be done in a later section dedicated to describing how to define DMA device master IDs

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

+- **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.

Addressed in 04edb5e.

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

+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.

Addressed in 04edb5e.

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

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

Signed-off-by: Daniel Oliveira <drawnpoetry@gmail.com>

I'm in charge now of this PR, therefore I'm withdrawing as a reviewer.

danielRep · 2025-08-08T17:56:46Z

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

I'm taking over this PR.

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

Diogo21Costa reviewed Feb 5, 2024

View reviewed changes

Comment thread source/bao_hyp/user_manual/porting.rst Outdated

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 previously requested changes Feb 15, 2024

View reviewed changes

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

Comment thread source/bao_hyp/user_manual/porting.rst

Comment thread source/bao_hyp/user_manual/porting.rst Outdated

Comment thread source/bao_hyp/user_manual/porting.rst Outdated

Comment thread source/bao_hyp/user_manual/porting.rst

danielRep force-pushed the wip/porting_guide branch 2 times, most recently from 11de124 to 4d5c5b3 Compare August 8, 2025 17:43

josecm and others added 2 commits August 8, 2025 18:48

feat(porting): add porting guide

85f02f6

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

fix: address all pr comments

5e32a79

Signed-off-by: Daniel Oliveira <drawnpoetry@gmail.com>

danielRep force-pushed the wip/porting_guide branch from 4d5c5b3 to 5e32a79 Compare August 8, 2025 17:49

danielRep removed their assignment Aug 8, 2025

danielRep requested review from DavidMCerdeira and Diogo21Costa August 8, 2025 17:50

danielRep requested review from danielRep and removed request for danielRep August 8, 2025 17:55

DavidMCerdeira self-assigned this Aug 8, 2025

		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

		- 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.

Conversation

josecm commented Jan 19, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danielRep left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danielRep commented Aug 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants