Add new guide to help those that are looking for to just getting started via emulation #605
Conversation
camilamacedo86
changed the title
|
Docs for 0606461 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2358/docs/artifacts/html/index.html |
camilamacedo86
requested review from
angolini,
kprosise,
caiotpereira and
vanmaegima
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
0606461
to
f5dc007
Compare
|
Docs for f5dc007 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2359/docs/artifacts/html/index.html |
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
f5dc007
to
709704d
Compare
|
Docs for 709704d are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2360/docs/artifacts/html/index.html |
|
Docs for 582b6be are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2361/docs/artifacts/html/index.html |
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
582b6be
to
9cd46e6
Compare
|
Docs for 9cd46e6 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2362/docs/artifacts/html/index.html |
There was a problem hiding this comment.
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
|
I'm a bit concerned that we will start to duplicate information with this PR, making the docs hard to maintain. |
|
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. |
|
Docs for dc09c24 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2363/docs/artifacts/html/index.html |
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
dc09c24
to
1eeeb60
Compare
|
Docs for 1eeeb60 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2364/docs/artifacts/html/index.html |
|
Docs for 22f03de are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2365/docs/artifacts/html/index.html |
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
22f03de
to
2317e9c
Compare
|
Docs for 2317e9c are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2366/docs/artifacts/html/index.html |
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
2317e9c
to
a36ac67
Compare
|
Docs for a36ac67 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2367/docs/artifacts/html/index.html |
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
a36ac67
to
a7ce8d3
Compare
|
Docs for a7ce8d3 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2368/docs/artifacts/html/index.html |
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
c2a9efa
to
1ece675
Compare
|
Docs for 1ece675 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2370/docs/artifacts/html/index.html |
There was a problem hiding this comment.
LGTM, thanks for the changes and the patience @camilamacedo86 !
| @@ -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`. | |||
There was a problem hiding this comment.
| 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.
|
|
||
| .. 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. |
There was a problem hiding this comment.
| 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. |
| --------------------------- | ||
|
|
||
| - 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`: |
There was a problem hiding this comment.
| - 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`: |
|
|
||
| 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. |
There was a problem hiding this comment.
| 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. |
|
|
||
| 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. |
There was a problem hiding this comment.
| 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. |
|
|
||
| 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. |
There was a problem hiding this comment.
| 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. |
|
|
||
| .. 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. |
There was a problem hiding this comment.
| 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. |
| .. 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. |
There was a problem hiding this comment.
| 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. |
| 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. |
There was a problem hiding this comment.
| 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. |
| 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`. |
There was a problem hiding this comment.
| 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
force-pushed
the
add-getting-start-with-qemu
branch
from
1ece675
to
3193818
Compare
|
Docs for 3193818 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2372/docs/artifacts/html/index.html |
…f use physical boards Signed-off-by: Camila Macedo <[email protected]>
camilamacedo86
force-pushed
the
add-getting-start-with-qemu
branch
from
3193818
to
cb13ca4
Compare
|
Docs for cb13ca4 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2374/docs/artifacts/html/index.html |
Readiness
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..."
make linkcheck.-s, --signoff).-S, --gpg-sign).Comments
Any thing else that a maintainer/reviewer should know.
This could include potential issues, rational for approach, etc.