github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-21 21:19:35 +00:00
Code Issues Projects Releases Wiki Activity

doc: update GSG for v0.1, add console code-block

Browse Source 
Console screen shots are hard to maintain, so use the
.. code-block:: console directive to show terminal console-like display
(black background with white text)

Change existing .. code-block:: console uses to .. code-block: none

Replace screen-shot images in apl-nuc getting started guide with
text-based console display.

Update apl-nuc GSG content with v0.1 changes

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2018-07-16 13:29:58 -07:00 committed by David Kinder
parent 1c712c52f9
commit e04255822a
8 changed files with 102 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/developer-guides/contribute_guidelines.rst
View File

@ -171,7 +171,7 @@ The name in the commit message ``Signed-off-by:`` line and your email must
match the change authorship information. Make sure your :file:`.gitconfig` match the change authorship information. Make sure your :file:`.gitconfig`
is set up correctly by using: is set up correctly by using:
.. code-block:: console .. code-block:: none
git config --global user.name "David Developer" git config --global user.name "David Developer"
git config --global user.email "david.developer@company.com" git config --global user.email "david.developer@company.com"

105
doc/getting-started/apl-nuc.rst
View File

@ -36,13 +36,14 @@ on your platform. You'll need a network connection for your platform to
complete this setup. complete this setup.
.. note:: .. note::
ACRN requires Clear Linux version 22140 or newer. The instructions below
have been validated with version 22140 and need some adjustment to work ACRN v0.1 (and the current master branch) requires Clear Linux
with newer versions. You will see a note when the instruction needs to be version 23690 or newer. If you use a newer version of Clear Linux,
adjusted. you'll need to adjust the instructions below to reference the version
number of Clear Linux you are using.
#. Download the compressed Clear installer image from #. Download the compressed Clear installer image from
https://download.clearlinux.org/releases/22140/clear/clear-22140-installer.img.xz https://download.clearlinux.org/releases/23690/clear/clear-23690-installer.img.xz
and follow the `Clear Linux installation guide and follow the `Clear Linux installation guide
<https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install>`__ <https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install>`__
as a starting point for installing Clear Linux onto your platform. Follow the recommended as a starting point for installing Clear Linux onto your platform. Follow the recommended
@ -61,11 +62,20 @@ complete this setup.
# swupd autoupdate --disable # swupd autoupdate --disable
#. If you have an older version of Clear Linux already installed
on your hardware, use this command to upgrade Clear Linux
to version 23690 (or newer):
.. code-block:: none
# swupd update -m 23690 # or newer version
#. Use the ``swupd bundle-add`` command and add these Clear Linux bundles: #. Use the ``swupd bundle-add`` command and add these Clear Linux bundles:
.. code-block:: none .. code-block:: none
# swupd bundle-add vim network-basic service-os kernel-pk # swupd bundle-add vim network-basic service-os kernel-pk \
desktop openssh-server
.. table:: Clear Linux bundles .. table:: Clear Linux bundles
:widths: auto :widths: auto
@ -84,6 +94,12 @@ complete this setup.
| kernel-pk | Run the Intel "PK" kernel(product kernel source) | | kernel-pk | Run the Intel "PK" kernel(product kernel source) |
| | and enterprise-style kernel with backports | | | and enterprise-style kernel with backports |
+--------------------+---------------------------------------------------+ +--------------------+---------------------------------------------------+
| desktop | Graphical desktop application, with Weston |
| | compositing window manager included |
+--------------------+---------------------------------------------------+
| openssh-server | Server-side support for secure connectivity and |
| | remote login using the SSH protocol |
+--------------------+---------------------------------------------------+
Add the ACRN hypervisor to the EFI Partition Add the ACRN hypervisor to the EFI Partition
============================================ ============================================
@ -99,9 +115,9 @@ partition. Follow these steps:
# ls -1 /mnt/EFI/org.clearlinux # ls -1 /mnt/EFI/org.clearlinux
bootloaderx64.efi bootloaderx64.efi
kernel-org.clearlinux.native.4.16.6-563 kernel-org.clearlinux.native.4.17.6-590
kernel-org.clearlinux.pk414-sos.4.14.34-28 kernel-org.clearlinux.pk414-sos.4.14.52-63
kernel-org.clearlinux.pk414-standard.4.14.34-28 kernel-org.clearlinux.pk414-standard.4.14.52-63
loaderx64.efi loaderx64.efi
.. note:: .. note::
@ -214,24 +230,31 @@ partition. Follow these steps:
# clr-boot-manager set-timeout 20 # clr-boot-manager set-timeout 20
# clr-boot-manager update # clr-boot-manager update
#. Reboot and select "The ACRN Service OS" to boot, as shown in #. Reboot and select "The ACRN Service OS" to boot, as shown below:
:numref:`gsg-bootmenu`:
.. figure:: images/gsg-bootmenu.png
:align: center
:width: 650px
:name: gsg-bootmenu
ACRN Service OS Boot menu .. code-block:: console
:emphasize-lines: 1
:caption: ACRN Service OS Boot Menu
=> The ACRN Service OS
Clear Linux OS for Intel Architecture (Clear-linux-native-4.17.6.590)
Clear Linux OS for Intel Architecture (Clear-linux-pk414-sos-4.14.52.63)
Clear Linux OS for Intel Architecture (Clear-linux-pk414-standard-4.14.52.63)
EFI Default Loader
Reboot Into Firmware Interface
#. After booting up the ACRN hypervisor, the Service OS will be launched #. After booting up the ACRN hypervisor, the Service OS will be launched
automatically by default, as shown in :numref:`gsg-sos-console`: automatically by default, as shown here:
.. figure:: images/gsg-sos-console.png .. code-block:: console
:align: center :caption: Service OS Console
:name: gsg-sos-console
Service OS Console clr-7259a7c5bbdd4bcaa9a59d5841b4ace login: root
You are required to change your password immediately (administrator enforced)
New password:
Retype new password:
root@clr-7259a7c5bbdd4bcaa9a59d5841b4ace ~ # _
.. note:: You may need to hit ``Enter`` to get a clean login prompt .. note:: You may need to hit ``Enter`` to get a clean login prompt
@ -249,13 +272,13 @@ automatically enabled after a system restart.
Set up Reference UOS Set up Reference UOS
==================== ====================
#. On your platform, download the pre-built reference Clear Linux UOS image into your #. On your platform, download the pre-built reference Clear Linux UOS
(root) home directory: image version 23690 (or newer) into your (root) home directory:
.. code-block:: none .. code-block:: none
# cd ~ # cd ~
# curl -O https://download.clearlinux.org/releases/22140/clear/clear-22140-kvm.img.xz # curl -O https://download.clearlinux.org/releases/23690/clear/clear-23690-kvm.img.xz
.. note:: .. note::
In case you want to use or try out a newer version of Clear Linux as the UOS, you can In case you want to use or try out a newer version of Clear Linux as the UOS, you can
@ -266,16 +289,16 @@ Set up Reference UOS
.. code-block:: none .. code-block:: none
# unxz clear-22140-kvm.img.xz # unxz clear-23690-kvm.img.xz
#. Deploy the UOS kernel modules to UOS virtual disk image (note: you'll need to use #. Deploy the UOS kernel modules to UOS virtual disk image (note: you'll need to use
the same **standard** image version number noted in step 1 above): the same **standard** image version number noted in step 1 above):
.. code-block:: none .. code-block:: none
# losetup -f -P --show /root/clear-22140-kvm.img # losetup -f -P --show /root/clear-23690-kvm.img
# mount /dev/loop0p3 /mnt # mount /dev/loop0p3 /mnt
# cp -r /usr/lib/modules/4.14.34-28.pk414-standard /mnt/lib/modules/ # cp -r /usr/lib/modules/4.14.52-63.pk414-standard /mnt/lib/modules/
# umount /mnt # umount /mnt
# sync # sync
@ -294,7 +317,7 @@ Set up Reference UOS
.. note:: .. note::
In case you have downloaded a different Clear Linux image than the one above In case you have downloaded a different Clear Linux image than the one above
(``clear-22140-kvm.img.xz``), you will need to modify the Clear Linux file name (``clear-23690-kvm.img.xz``), you will need to modify the Clear Linux file name
and version number highlighted above (the ``-s 3,virtio-blk`` argument) to match and version number highlighted above (the ``-s 3,virtio-blk`` argument) to match
what you have downloaded above. Likewise, you may need to adjust the kernel file what you have downloaded above. Likewise, you may need to adjust the kernel file
name on the second line highlighted (check the exact name to be used using: name on the second line highlighted (check the exact name to be used using:
@ -359,7 +382,7 @@ each with their own way to install development tools:
* On a Clear Linux development system, install the ``os-clr-on-clr`` bundle to get * On a Clear Linux development system, install the ``os-clr-on-clr`` bundle to get
the necessary tools: the necessary tools:
.. code-block:: console .. code-block:: none
$ sudo swupd bundle-add os-clr-on-clr $ sudo swupd bundle-add os-clr-on-clr
$ sudo swupd bundle-add python3-basic $ sudo swupd bundle-add python3-basic
@ -367,7 +390,7 @@ each with their own way to install development tools:
* On a Ubuntu/Debian development system: * On a Ubuntu/Debian development system:
.. code-block:: console .. code-block:: none
$ sudo apt install gcc \ $ sudo apt install gcc \
git \ git \
@ -390,7 +413,7 @@ each with their own way to install development tools:
* On a Fedora/Redhat development system: * On a Fedora/Redhat development system:
.. code-block:: console .. code-block:: none
$ sudo dnf install gcc \ $ sudo dnf install gcc \
git \ git \
@ -411,7 +434,7 @@ each with their own way to install development tools:
* On a CentOS development system: * On a CentOS development system:
.. code-block:: console .. code-block:: none
$ sudo yum install gcc \ $ sudo yum install gcc \
git \ git \
@ -447,7 +470,7 @@ repository has three main components in it:
You can build all these components in one go as follows: You can build all these components in one go as follows:
.. code-block:: console .. code-block:: none
$ git clone https://github.com/projectacrn/acrn-hypervisor $ git clone https://github.com/projectacrn/acrn-hypervisor
$ cd acrn-hypervisor $ cd acrn-hypervisor
@ -466,7 +489,7 @@ and are using it as the current working directory.
#. Build the ACRN hypervisor. #. Build the ACRN hypervisor.
.. code-block:: console .. code-block:: none
$ cd hypervisor $ cd hypervisor
$ make PLATFORM=uefi $ make PLATFORM=uefi
@ -475,7 +498,7 @@ and are using it as the current working directory.
#. Build the ACRN device model (included in the acrn-hypervisor repo): #. Build the ACRN device model (included in the acrn-hypervisor repo):
.. code-block:: console .. code-block:: none
$ cd ../devicemodel $ cd ../devicemodel
$ make $ make
@ -484,7 +507,7 @@ and are using it as the current working directory.
#. Build the ACRN tools (included in the acrn-hypervisor repo): #. Build the ACRN tools (included in the acrn-hypervisor repo):
.. code-block:: console .. code-block:: none
$ cd ../tools $ cd ../tools
$ for d in */; do make -C "$d"; done $ for d in */; do make -C "$d"; done
@ -507,7 +530,7 @@ based on the platform selected, assuming that you are under the top-level
directory of acrn-hypervisor. The configuration file, named ``.config``, can be directory of acrn-hypervisor. The configuration file, named ``.config``, can be
found under the target folder of your build. found under the target folder of your build.
.. code-block:: console .. code-block:: none
$ cd hypervisor $ cd hypervisor
$ make defconfig PLATFORM=uefi $ make defconfig PLATFORM=uefi
@ -526,7 +549,7 @@ are under the top-level directory of acrn-hypervisor, generate a default
configuration file for UEFI, allow you to modify some configurations and build configuration file for UEFI, allow you to modify some configurations and build
the hypervisor using the updated ``.config``. the hypervisor using the updated ``.config``.
.. code-block:: console .. code-block:: none
$ cd hypervisor $ cd hypervisor
$ make defconfig PLATFORM=uefi $ make defconfig PLATFORM=uefi
@ -538,7 +561,7 @@ the hypervisor using the updated ``.config``.
Refer to the help on menuconfig for a detailed guide on the interface. Refer to the help on menuconfig for a detailed guide on the interface.
.. code-block:: console .. code-block:: none
$ pydoc3 menuconfig $ pydoc3 menuconfig
@ -550,7 +573,7 @@ Currently the ACRN hypervisor looks for default configurations under
specified platform. The following steps allow you to create a defconfig for specified platform. The following steps allow you to create a defconfig for
another platform based on a current one. another platform based on a current one.
.. code-block:: console .. code-block:: none
$ cd hypervisor $ cd hypervisor
$ make defconfig PLATFORM=uefi $ make defconfig PLATFORM=uefi
@ -561,6 +584,6 @@ another platform based on a current one.
Then you can re-use that configuration by passing the name (``xxx`` in the Then you can re-use that configuration by passing the name (``xxx`` in the
example above) to 'PLATFORM=': example above) to 'PLATFORM=':
.. code-block:: console .. code-block:: none
$ make defconfig PLATFORM=xxx $ make defconfig PLATFORM=xxx

BIN
doc/getting-started/images/gsg-bootmenu.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 123 KiB

BIN
doc/getting-started/images/gsg-sos-console.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 14 KiB

8
doc/getting-started/up2.rst
View File

@ -48,7 +48,7 @@ You will need to keep these in mind in a few places:
* When mounting the EFI System Partition (ESP) * When mounting the EFI System Partition (ESP)
.. code-block:: console .. code-block:: none
# mount /dev/mmcblk0p1 /mnt # mount /dev/mmcblk0p1 /mnt
@ -58,7 +58,7 @@ You will need to keep these in mind in a few places:
* When configuring the EFI firmware to boot the ACRN hypervisor by default * When configuring the EFI firmware to boot the ACRN hypervisor by default
.. code-block:: console .. code-block:: none
# efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/mmcblk0 -p 1 -L "ACRN Hypervisor" \ # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/mmcblk0 -p 1 -L "ACRN Hypervisor" \
-u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=mmio@0x9141e000" -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=mmio@0x9141e000"
@ -69,7 +69,7 @@ UP2 serial port setting
The serial port in the 40-pin HAT connector is located at ``MMIO 0x0x9141e000``. The serial port in the 40-pin HAT connector is located at ``MMIO 0x0x9141e000``.
You can check this from the ``dmesg`` output from the initial Clearlinux installation. You can check this from the ``dmesg`` output from the initial Clearlinux installation.
.. code-block:: console .. code-block:: none
# dmesg | grep dw-apb-uart # dmesg | grep dw-apb-uart
[2.150689] dw-apb-uart.8: ttyS1 at MMIO 0x91420000 (irq = 4, base_baud = 115200) is a 16550A [2.150689] dw-apb-uart.8: ttyS1 at MMIO 0x91420000 (irq = 4, base_baud = 115200) is a 16550A
@ -86,7 +86,7 @@ throughout the :ref:`getting_started` therefore is ``/dev/mmcblk0``
The UUID of the partition ``/dev/mmcblk0p3`` can be found by The UUID of the partition ``/dev/mmcblk0p3`` can be found by
.. code-block:: console .. code-block:: none
# blkid /dev/mmcblk # blkid /dev/mmcblk

16
doc/static/acrn-custom.css vendored
View File

@ -14,6 +14,22 @@
} }
*/ */
/* pygments tweak for white-on-black console */
.highlight-console .highlight {
background-color: black;
}
.highlight-console .highlight .go, .highlight-console .highlight .gp {
color: white;
}
.highlight-console .highlight .hll {
background-color: white;
}
.highlight-console .highlight .hll .go, .highlight-console .highlight .hll .gp {
color: black;
font-weight: bold;
}
/* tweak doc version selection /* tweak doc version selection
.rst-versions { .rst-versions {
position: static; position: static;

4
doc/tutorials/static-ip.rst
View File

@ -26,7 +26,7 @@ You can set up a static IP address by copying the
``/etc/systemd/network/`` directory. You can create this directory and ``/etc/systemd/network/`` directory. You can create this directory and
copy the file with the following command: copy the file with the following command:
.. code-block:: console .. code-block:: none
mkdir -p /etc/systemd/network mkdir -p /etc/systemd/network
cp /usr/lib/systemd/network/50-eth.network /etc/systemd/network cp /usr/lib/systemd/network/50-eth.network /etc/systemd/network
@ -61,7 +61,7 @@ Activate the new configuration
You do not need to reboot the machine after making the changes to the system, the You do not need to reboot the machine after making the changes to the system, the
following steps that restart the ``systemd-networkd`` service will suffice (run as ``root``): following steps that restart the ``systemd-networkd`` service will suffice (run as ``root``):
.. code-block:: console .. code-block:: none
systemctl daemon-reload systemctl daemon-reload
systemctl restart systemd-networkd systemctl restart systemd-networkd

30
doc/tutorials/using_ubuntu_as_sos.rst
View File

@ -29,7 +29,7 @@ Ubuntu 16.04.4 LTS was used throughout this document, other versions such as
mechanism for accessing the Service OS remotely or when running one or more mechanism for accessing the Service OS remotely or when running one or more
User OS (UOS). Follow these steps to enable it on the Ubuntu SOS: User OS (UOS). Follow these steps to enable it on the Ubuntu SOS:
.. code-block:: console .. code-block:: none
sudo apt-get install openssh-server sudo apt-get install openssh-server
sudo service ssh status sudo service ssh status
@ -49,7 +49,7 @@ the source code, build it, and install it on your device.
#. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_ #. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_
code repository code repository
.. code-block:: console .. code-block:: none
cd ~ cd ~
git clone https://github.com/projectacrn/acrn-hypervisor git clone https://github.com/projectacrn/acrn-hypervisor
@ -64,7 +64,7 @@ the source code, build it, and install it on your device.
Here is the short version of how to build and install ACRN from source. Here is the short version of how to build and install ACRN from source.
.. code-block:: console .. code-block:: none
cd ~/acrn-hypervisor cd ~/acrn-hypervisor
make PLATFORM=uefi make PLATFORM=uefi
@ -83,7 +83,7 @@ the source code, build it, and install it on your device.
#. Mount the EFI System Partition (ESP) and add the ACRN hypervisor and #. Mount the EFI System Partition (ESP) and add the ACRN hypervisor and
Service OS kernel to it (as ``root``) Service OS kernel to it (as ``root``)
.. code-block:: console .. code-block:: none
sudo umount /boot/efi sudo umount /boot/efi
sudo lsblk sudo lsblk
@ -98,14 +98,14 @@ the source code, build it, and install it on your device.
#. Install the hypervisor (``acrn.efi``) #. Install the hypervisor (``acrn.efi``)
.. code-block:: console .. code-block:: none
sudo mkdir /mnt/EFI/acrn/ sudo mkdir /mnt/EFI/acrn/
sudo cp ~/acrn-hypervisor/build/hypervisor/acrn.efi /mnt/EFI/acrn sudo cp ~/acrn-hypervisor/build/hypervisor/acrn.efi /mnt/EFI/acrn
#. Configure the EFI firmware to boot the ACRN hypervisor by default #. Configure the EFI firmware to boot the ACRN hypervisor by default
.. code-block:: console .. code-block:: none
sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 \ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 \
-L "ACRN Hypervisor" -u "bootloader=\EFI\ubuntu\grubx64.efi" -L "ACRN Hypervisor" -u "bootloader=\EFI\ubuntu\grubx64.efi"
@ -131,7 +131,7 @@ few steps.
a. Download and extract the Service OS kernel a. Download and extract the Service OS kernel
.. code-block:: console .. code-block:: none
mkdir ~/kernel-build mkdir ~/kernel-build
cd ~/kernel-build cd ~/kernel-build
@ -141,7 +141,7 @@ a. Download and extract the Service OS kernel
#. Install the SOS kernel and its drivers (modules) #. Install the SOS kernel and its drivers (modules)
.. code-block:: console .. code-block:: none
sudo cp -r ~/kernel-build/usr/lib/modules/4.14.41-39.pk414-sos/ /lib/modules/ sudo cp -r ~/kernel-build/usr/lib/modules/4.14.41-39.pk414-sos/ /lib/modules/
sudo cp ~/kernel-build/usr/lib/kernel/org.clearlinux.pk414-sos.4.14.41-39 /boot/acrn/ sudo cp ~/kernel-build/usr/lib/kernel/org.clearlinux.pk414-sos.4.14.41-39 /boot/acrn/
@ -176,7 +176,7 @@ a. Download and extract the Service OS kernel
* Update Grub on your system * Update Grub on your system
.. code-block:: console .. code-block:: none
sudo update-grub sudo update-grub
@ -211,7 +211,7 @@ We are using a User OS based on `Clear Linux`_.
* Download the Clear Linux image from `<https://download.clearlinux.org>`_ * Download the Clear Linux image from `<https://download.clearlinux.org>`_
.. code-block:: console .. code-block:: none
cd ~ cd ~
wget https://download.clearlinux.org/releases/22780/clear/clear-22780-kvm.img.xz wget https://download.clearlinux.org/releases/22780/clear/clear-22780-kvm.img.xz
@ -219,14 +219,14 @@ We are using a User OS based on `Clear Linux`_.
* Download the Production Kenrel (PK) kernel * Download the Production Kenrel (PK) kernel
.. code-block:: console .. code-block:: none
wget https://download.clearlinux.org/releases/22780/clear/x86_64/os/Packages/linux-pk414-standard-4.14.47-44.x86_64.rpm wget https://download.clearlinux.org/releases/22780/clear/x86_64/os/Packages/linux-pk414-standard-4.14.47-44.x86_64.rpm
rpm2cpio linux-pk414-standard-4.14.47-44.x86_64.rpm | cpio -idmv rpm2cpio linux-pk414-standard-4.14.47-44.x86_64.rpm | cpio -idmv
* Update the UOS kernel modules * Update the UOS kernel modules
.. code-block:: console .. code-block:: none
sudo losetup -f -P --show /root/clear-22789-kvm.img sudo losetup -f -P --show /root/clear-22789-kvm.img
sudo mount /dev/loop0p3 /mnt sudo mount /dev/loop0p3 /mnt
@ -237,13 +237,13 @@ We are using a User OS based on `Clear Linux`_.
If you encounter a permission issue, follow these steps: If you encounter a permission issue, follow these steps:
.. code-block:: console .. code-block:: none
sudo chmod 777 /dev/acrn_vhm sudo chmod 777 /dev/acrn_vhm
* One additional package is needed * One additional package is needed
.. code-block:: console .. code-block:: none
sudo apt-get instal iasl sudo apt-get instal iasl
sudo cp /usr/bin/iasl /usr/sbin/iasl sudo cp /usr/bin/iasl /usr/sbin/iasl
@ -263,7 +263,7 @@ Start the User OS (UOS)
You are now all set to start the User OS (UOS) You are now all set to start the User OS (UOS)
.. code-block:: console .. code-block:: none
sudo /usr/share/acrn/samples/nuc/launch_uos.sh sudo /usr/share/acrn/samples/nuc/launch_uos.sh