Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add new guide to help those that are looking for to just getting started via emulation #605

Merged
merged 1 commit into from
Sep 28, 2023
Merged

Add new guide to help those that are looking for to just getting started via emulation #605

merged 1 commit into from
Sep 28, 2023

Conversation

camilamacedo86
Copy link
Contributor

@camilamacedo86 camilamacedo86 commented Sep 23, 2023 •
edited
Loading

Readiness

  • Merge (pending reviews)
  • Merge after date or event
  • Draft

Overview

Upon following the guides, it is unclear whether the steps in the "Flashing Your Device" section are the same as those required to emulate with QEMU. Additionally, each factory requires a unique set of artefacts, and the command to run with QEMU varies.

When just getting started, users likely do not concern themselves with the specifics of the platform; they simply want to understand how the solution works. Therefore, this PR proposes adding a new guide to allow users to easily copy and paste commands, flash an image with QEMU, and proceed to the next tutorials.

Checklist

Optional. Add a 'x' to steps taken.
You can fill this out after opening the PR. "Did I..."

  • Run spelling and grammar check, preferably with linter.
  • Avoid changing any header associated with a link/reference.
  • Step through instructions (or ask someone to do so).
  • Review for wordiness
  • Match tone and style of page/section.
  • Run make linkcheck.
  • View HTML in a browser to check rendering.
  • Use semantic newlines.
  • follow best practices for commits.
    • Descriptive title written in the imperative.
    • Include brief overview of QA steps taken.
    • Mention any related issues numbers.
    • End message with sign off/DCO line (-s, --signoff).
    • Sign commit with your gpg key (-S, --gpg-sign).
    • Squash commits if needed.
  • Request PR review by a technical writer and at least one peer.

Comments

Any thing else that a maintainer/reviewer should know.
This could include potential issues, rational for approach, etc.

@camilamacedo86 camilamacedo86 changed the title Add new guide to help those that are looking for to emulate instead o… Add new guide to help those that are looking for to just getting started via emulation Sep 23, 2023
@doanac
Copy link
Member

doanac commented Sep 23, 2023

Docs for 0606461 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2358/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from 0606461 to f5dc007 Compare September 23, 2023 10:35
@doanac
Copy link
Member

doanac commented Sep 23, 2023

Docs for f5dc007 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2359/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 removed the request for review from angolini September 23, 2023 10:38
@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from f5dc007 to 709704d Compare September 23, 2023 10:41
@doanac
Copy link
Member

doanac commented Sep 23, 2023

Docs for 709704d are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2360/docs/artifacts/html/index.html

@doanac
Copy link
Member

doanac commented Sep 23, 2023

Docs for 582b6be are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2361/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from 582b6be to 9cd46e6 Compare September 23, 2023 21:58
@doanac
Copy link
Member

doanac commented Sep 23, 2023

Docs for 9cd46e6 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2362/docs/artifacts/html/index.html

angolini
angolini approved these changes Sep 25, 2023
View reviewed changes
Copy link
Collaborator

@angolini angolini left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like to me that it would be good to have a link to this pages added to https://docs.foundries.io/latest/getting-started/flash-device/index.html

I would use hard wrap based on semantic line breaks

But those are only suggestions. LGTM

source/index.rst Show resolved Hide resolved
@vanmaegima
Copy link
Member

I'm a bit concerned that we will start to duplicate information with this PR, making the docs hard to maintain.
We had a discussion in the past about making all of out Getting Started steps using QEMU. I would rather go this way than creating a new page like this.

vanmaegima
vanmaegima requested changes Sep 25, 2023
View reviewed changes
source/getting-started/emulation-with-qemu/index.rst Outdated Show resolved Hide resolved
source/getting-started/emulation-with-qemu/index.rst Outdated Show resolved Hide resolved
source/getting-started/emulation-with-qemu/index.rst Show resolved Hide resolved
source/getting-started/emulation-with-qemu/index.rst Outdated Show resolved Hide resolved
source/getting-started/emulation-with-qemu/index.rst Outdated Show resolved Hide resolved
source/getting-started/flash-device/index.rst Outdated Show resolved Hide resolved
@vanmaegima
Copy link
Member

My suggestion would be to fix the content in https://docs.foundries.io/latest/reference-manual/qemu/arm64.html (as well as other QEMU pages) for better support, then point this page in the getting started.

@doanac
Copy link
Member

doanac commented Sep 25, 2023

Docs for dc09c24 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2363/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from dc09c24 to 1eeeb60 Compare September 25, 2023 16:13
@doanac
Copy link
Member

doanac commented Sep 25, 2023

Docs for 1eeeb60 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2364/docs/artifacts/html/index.html

@vanmaegima vanmaegima self-requested a review September 25, 2023 16:45
@doanac
Copy link
Member

doanac commented Sep 25, 2023

Docs for 22f03de are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2365/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from 22f03de to 2317e9c Compare September 25, 2023 17:47
@doanac
Copy link
Member

doanac commented Sep 25, 2023

Docs for 2317e9c are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2366/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from 2317e9c to a36ac67 Compare September 25, 2023 17:52
@doanac
Copy link
Member

doanac commented Sep 25, 2023

Docs for a36ac67 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2367/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from a36ac67 to a7ce8d3 Compare September 25, 2023 17:57
@doanac
Copy link
Member

doanac commented Sep 25, 2023

Docs for a7ce8d3 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2368/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from c2a9efa to 1ece675 Compare September 26, 2023 07:17
@doanac
Copy link
Member

doanac commented Sep 26, 2023

Docs for 1ece675 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2370/docs/artifacts/html/index.html

vanmaegima
vanmaegima approved these changes Sep 26, 2023
View reviewed changes
Copy link
Member

@vanmaegima vanmaegima left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks for the changes and the patience @camilamacedo86 !

MrCry0
MrCry0 approved these changes Sep 26, 2023
View reviewed changes
Copy link
Contributor

@MrCry0 MrCry0 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

kprosise
kprosise reviewed Sep 26, 2023
View reviewed changes
Copy link
Contributor

@kprosise kprosise left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this addition! I left some suggestions, mostly related to markup style, which doesn't change how it is rendered.
One additional note: I would move reference-manual/qemu/emulation-with-qemu/ to getting-started/emulation-with-qemu/

source/getting-started/flash-device/index.rst Outdated
@@ -21,6 +21,10 @@ Prerequisites and Pre-Work
- Ethernet cable (if choosing Wired)
- Console access to your hardware via UART serial (if choosing WiFi)

.. note::

If you're starting out and prefer emulation over a physical board, refer to the guide :ref:`gs-emulation-with-qemu`. This guide will walk you through "Flashing the Image," allowing you to move on to :ref:`gs-register`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you're starting out and prefer emulation over a physical board, refer to the guide :ref:`gs-emulation-with-qemu`. This guide will walk you through "Flashing the Image," allowing you to move on to :ref:`gs-register`.
If you're starting out and prefer emulation over a physical board, refer to the guide :ref:`gs-emulation-with-qemu`.
This guide will walk you through "Flashing the Image," allowing you to move on to :ref:`gs-register`.

Semantic newline added.
It is a Guideline more than a hard rule, but we try and keep it to one sentence per line.
Just for reference, not related to this PR:
If a sentence is long (well past column 100) and can not be shortened or split into multiple,
aim to add a newline where logical, such as after a comma, colon, or semicolon. But first try and shorten the sentence, aiming for less than 25 words.

source/reference-manual/qemu/emulation-with-qemu/index.rst Outdated

.. note::

This tutorial is designed to assist you in getting started with using QEMU to emulate devices on your desktop. Please note that we are selecting a specific FoundriesFactory® to establish an environment for experimenting with the Foundries.io™ solution. This approach will enable you to engage with subsequent tutorials and enhance your skills.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This tutorial is designed to assist you in getting started with using QEMU to emulate devices on your desktop. Please note that we are selecting a specific FoundriesFactory® to establish an environment for experimenting with the Foundries.io™ solution. This approach will enable you to engage with subsequent tutorials and enhance your skills.
This tutorial is designed to assist you in getting started with using QEMU to emulate devices on your desktop.
Please note that we are selecting a specific machine to establish an environment for experimenting with FoundriesFactory®.
This approach will enable you to engage with subsequent tutorials and enhance your skills.

source/reference-manual/qemu/emulation-with-qemu/index.rst Outdated
---------------------------

- Ensure that you have installed `QEMU <https://www.qemu.org/download/>`_ 5.2 or later.
- Create a :ref:`ref-factory` for the platform ``QEMU Arm 64 bit`` as described in the guide :ref:`gs-select-platform`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Create a :ref:`ref-factory` for the platform ``QEMU Arm 64 bit`` as described in the guide :ref:`gs-select-platform`:
- Create a :ref:`ref-factory` for the ``QEMU Arm 64 bit`` platform as described in the guide :ref:`gs-select-platform`:

source/reference-manual/qemu/emulation-with-qemu/index.rst Outdated

5. Convert the Disk to QCOW2 Format:

Use ``qemu-img`` to convert your raw disk image to the QCOW2 format. This step can sometimes make the image more amenable to virtualization.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Use ``qemu-img`` to convert your raw disk image to the QCOW2 format. This step can sometimes make the image more amenable to virtualization.
Use ``qemu-img`` to convert your raw disk image to the QCOW2 format.
This step can sometimes make the image more amenable to virtualization.

source/reference-manual/qemu/emulation-with-qemu/index.rst Outdated

6. Resize the Image:

Resize the new QCOW2 image to a size that’s a multiple of the sector size. Let’s resize it to 4GB for simplicity.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Resize the new QCOW2 image to a size that’s a multiple of the sector size. Let’s resize it to 4GB for simplicity.
Resize the new QCOW2 image to a size that’s a multiple of the sector size.
Let us resize it to 4GB for simplicity.

source/reference-manual/qemu/emulation-with-qemu/index.rst Outdated

8. Log into the booted system:

By default, the ``username`` and ``password`` to log in your device after boot are ``fio/fio``. We recommend changing them once you are in development.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
By default, the ``username`` and ``password`` to log in your device after boot are ``fio/fio``. We recommend changing them once you are in development.
By default, the ``username`` and ``password`` to log in your device after boot are ``fio/fio``.
We recommend changing them once you are in development.

source/reference-manual/qemu/emulation-with-qemu/index.rst Outdated

.. note::

If you encounter a QEMU terminal where common commands like ``ls`` are unresponsive, it may indicate an issue. A missing login prompt likely means that your image did not boot successfully.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you encounter a QEMU terminal where common commands like ``ls`` are unresponsive, it may indicate an issue. A missing login prompt likely means that your image did not boot successfully.
If you encounter a QEMU terminal where common commands like ``ls`` are unresponsive, it may indicate an issue.
A missing login prompt likely means that your image did not boot successfully.

source/reference-manual/qemu/emulation-with-qemu/index.rst Outdated
.. note::

If you encounter a QEMU terminal where common commands like ``ls`` are unresponsive, it may indicate an issue. A missing login prompt likely means that your image did not boot successfully.
For this specific platform, we use the ``-bios=flash.bin`` flag to boot the system. However, the flags and configurations may vary based on the selected platform.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For this specific platform, we use the ``-bios=flash.bin`` flag to boot the system. However, the flags and configurations may vary based on the selected platform.
For this specific platform, we use the ``-bios=flash.bin`` flag to boot the system.
However, the flags and configurations may vary based on the selected platform.

source/reference-manual/qemu/emulation-with-qemu/index.rst Outdated
Next Step
--------------------------

At this point, you have successfully set up the device. You are now able to :ref:`gs-register` and proceed with the following tutorials.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
At this point, you have successfully set up the device. You are now able to :ref:`gs-register` and proceed with the following tutorials.
At this point, you have successfully set up the device.
You are now able to :ref:`gs-register` and proceed with the following tutorials.

source/reference-manual/qemu/qemu.rst Outdated
x86_64
arm
arm64
riscv64

.. note::

If you're just starting and prefer emulation, refer to the guide :ref:`gs-emulation-with-qemu`. This guide achieves the same result as :ref:`gs-flash-device`. Afterward, you can proceed with the subsequent steps to :ref:`gs-register`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you're just starting and prefer emulation, refer to the guide :ref:`gs-emulation-with-qemu`. This guide achieves the same result as :ref:`gs-flash-device`. Afterward, you can proceed with the subsequent steps to :ref:`gs-register`.
If you're just starting and prefer emulation, refer to the guide :ref:`gs-emulation-with-qemu`.
This guide achieves the same result as :ref:`gs-flash-device`.
Afterward, you can proceed with the subsequent steps to :ref:`gs-register`.

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from 1ece675 to 3193818 Compare September 27, 2023 08:20
@doanac
Copy link
Member

doanac commented Sep 27, 2023

Docs for 3193818 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2372/docs/artifacts/html/index.html

@camilamacedo86 camilamacedo86 force-pushed the add-getting-start-with-qemu branch from 3193818 to cb13ca4 Compare September 27, 2023 11:29
@doanac
Copy link
Member

doanac commented Sep 27, 2023

Docs for cb13ca4 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2374/docs/artifacts/html/index.html

kprosise
kprosise approved these changes Sep 28, 2023
View reviewed changes
Copy link
Contributor

@kprosise kprosise left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I will proceed with merging! Thank you for doing this!

@kprosise kprosise merged commit 8e49333 into foundriesio:main Sep 28, 2023
1 check passed
@camilamacedo86 camilamacedo86 deleted the add-getting-start-with-qemu branch October 2, 2023 08:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kprosise kprosise kprosise approved these changes

@vanmaegima vanmaegima vanmaegima approved these changes

@angolini angolini angolini approved these changes

@MrCry0 MrCry0 MrCry0 approved these changes

@caiotpereira caiotpereira Awaiting requested review from caiotpereira

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@camilamacedo86 @doanac @vanmaegima @MrCry0 @angolini @kprosise