diff --git a/misc/packaging/README.rst b/misc/packaging/README.rst index c048e6117..e4e23e963 100644 --- a/misc/packaging/README.rst +++ b/misc/packaging/README.rst @@ -1,128 +1,231 @@ -.. _ubuntu_sos: +.. _debian_packaging: -ubuntu_sos -########## +ACRN Installation via Debian Packages +##################################### -Description -*********** -this scripts show how to build acrn-hypervisor and acrn-kernel deb package +Debian packages provide a simple way to build and package a collection +of ACRN configurations on a development system, based on a set of +hardware platforms and scenario choices. You can then copy the packages +onto your target platform, select a particular configuration and reboot +the system with ACRN and an Ubuntu Service VM up and running. -1. setup native ubuntu 18.04 -============================= -Base on GEO; config your proxy +Follow these instructions to build Debian packages for the acrn-hypervisor and +acrn-kernel, install them on your target system, and boot running ACRN. - .. code-block:: none +.. rst-class:: numbered-step - sudo apt install python3 +Set up Pre-requisites +********************* - sudo su +Your development system should be running Ubuntu +18.04 and be connected to the internet. (You'll be installing software +with ``apt`` and from Pypi and downloading ACRN software from +GitHub.) + +It's likely you've already got python3 on your system, but we can make +sure by installing it with:: + + sudo apt install python3 + +All of the Debian packaging work is handled by a script found in the +ACRN GitHub repo. If you don't have it downloaded already, clone the +ACRN repo with:: + + git clone https://github.com/projectacrn/acrn-hypervisor.git + +All the configuration files and scripts to build the Debian packages are +in the ``misc/packaging`` folder, so let's go there:: + + cd acrn-hypervisor/misc/packaging -2. config release.json file -============================ -below is explanation for items in release.json,please change item accordingly,if do not change means go with default value +.. rst-class:: numbered-step - .. code-block:: none +Configure Debian packaging details +********************************** - { +The build and packaging script ``install_uSoS.py`` does all the work to +build and make the Debian packages. You configure what the script does +by editing its configuration file, ``release.json``. Comments in the +JSON file document how you can adjust things to your specific needs. For +example, the default ``release.json`` file builds for all three default +ACRN configurations (industry, hybrid, and logical_partition) and for +two supported boards (nuc717dnb and whl-ipc-i5). - "//":"release ubuntu as sos verion", +.. important:: In the current implementation of this packaging script, if you + change the ``release.json`` boards configuration choices, you'll also need to + manually update the ``acrn-hypervisor.postinst`` script to match. - "install_package":"true",---------->this 1st time should set to true if you did not install acrn related compile package, if already install,set to false +Here's the default ``release.json`` configuration: - "gcc_version":"7.3.0",---------->gcc version should higher than 7.3.0 - - "binutils":"2.27",---------->binutils version should higher than 2.27 - - "//":"acrn-hypervisor config", - - "build_acrn":"true",---------->if you need build acrn-hypervisor set to true - - "sync_acrn_code":"true",---------->if you need sync acrn-hypervisor code set to true - - "acrn_repo":"https://github.com/projectacrn/acrn-hypervisor.git",---------->acrn repo - - "release_version":"remotes/origin/release_2.0",---------->acrn release branch - - "acrn_deb_package":"true",---------->if you need create acrn-hypervison deb set to true - - "install_acrn_deb":"false",---------->if you need install acrn-hypervisor deb set to true - - "build_cmd":---------->acrn-hypervisor build command must include scenario and board info and release type - - { - - "scenario": - - { - - "industry":"true", - - "hybrid":"true", - - "logical_partition":"true" +.. literalinclude:: release.json - }, +.. rst-class:: numbered-step - "board": +Run the package-building script +******************************* - { +The ``install_uSoS.py`` python script does all the work to install +needed tools (such as make, gnu-efi, libssl-dev, libpciaccess-dev, +uuid-dev, and more). It also verifies that tool versions (such as the +gcc compiler) are appropriate (as configured in the ``release.json`` +file). - "nuc7i7dnb":"true", +The script runs without further user input, and must be run with +``sudo``:: - "whl-ipc-i5":"true" + sudo python3 install_uSoS.py - }, +With the default ``release.json`` configuration, this script will run +for about 30 minutes, but could take longer depending on your internet +speed (for downloading files) and overall computer performance (for +compiling the Linux kernel, ACRN hypervisor, and ACRN tools). - "release":"0"---------->0 means debug version,1 means release version +When done, it creates two Debian packages: - }, + * ``acrn_deb_package.deb`` with the ACRN hypervisor and tools built + for each configuration combination, and + * ``acrn_kernel_deb_package.deb`` with the ACRN-patched Linux kernel. - "//":"kernel config", - - "build_acrn_kernel":"true",---------->if you need build acrn-kernel set to true - - "sync_acrn_kernel_code":"true",---------->if you need sync acrn-kernel code set to true - - "kernel_release_version":"remotes/origin/release_2.0",---------->acrn kernel release branch +You'll need to copy these two files onto your target system, either via +the network or simply by using a thumbdrive. - "sos_kernel_repo":"https://github.com/projectacrn/acrn-kernel.git",---------->acrn kernel repo +.. rst-class:: numbered-step + +Prepare your target system with Ubuntu 18.04 +******************************************** + +Your target system must be one of the choices listed in the ``release.json`` +file and should be running Ubuntu 18.04. Make sure it's updated using the +commands:: + + sudo apt update + sudo apt upgrade + +Reboot your system to complete the installation. + +.. rst-class:: numbered-step + +Install Debian packages on your target system +********************************************* + +Copy the Debian packages you created on your development system, for +example, using a thumbdrive. Then install the ACRN Debian package:: + + sudo dpkg -i acrn_deb_package.deb + +Make your choices for scenario, board, and which disk to use, +for example, this selects the industry scenario, nuc7i7dnb board, and +installation on the NVMe drive (input is highlighted): + +.. code-block:: console + :emphasize-lines: 11, 16, 23 + + Selecting previously unselected package acrn-package. + (Reading database ... 163871 files and directories currently installed.) + Preparing to unpack acrn_deb_package.deb... + Unpacking acrn-package (2020-07-17) ... + Setting up acrn-package (2020-07-17) ... + please choose , , + Scenario is -> + 1. industry + 2. hybrid + 3. logical_partition + 1 + Scenario is industry + Board is -> + 1. nuc7i7dnb + 2. whl-ipc-i5 + 1 + Board is nuc7i7dnb + Your acrn bin is -> + /boot/acrn.industry.nuc7i7dnb.bin + disk type is -> + 1. nvme + 2. sda + 1 + disk type is nvme + Sourcing file '/etc/default/grub' + Generating grub configuration file ... + Found linux image: /boot/vmlinuz-5.3.0-62-generic + Found initrd image: /boot/initrd.img-5.3.0-62-generic + Found linux image: /boot/vmlinuz-5.3.0-28-generic + Found initrd image: /boot/initrd.img-5.3.0-28-generic + Added boot menu entry for EFI firmware configuration + done + + - "acrn_kernel_deb_package":"true",---------->if you need create acrn-kernel deb set to true +Then install the ACRN-patched kernel package:: - "install_acrn_kernel_deb":"false",---------->if you need install acrn-kernel deb set to true + sudo dpkg -i acrn_kernel_deb_package.deb - "//":"misc", +After that, you're ready to reboot. - "auto_reboot":"false"---------->if you need reboot set to true +.. rst-class:: numbered-step - } +Boot ACRN using the multiboot2 grub choice +****************************************** -3.python3 install_uSoS.py -========================= -after finished , will get below two item +This time when you boot your target system you'll see some new options: -acrn_deb_package.deb +.. code-block:: console + :emphasize-lines: 4 -acrn_kernel_deb_package.deb + Ubuntu + Advanced options for Ubuntu + System setup + *ACRN multiboot2 + ACRN efi + +If your target system has a serial port active, you can simply hit +:kbd:`return` (or wait for the timeout) to boot with this +``ACRN multiboot2`` choice. + +.. important:: If you don't have an active serial port, you'll need to + edit the grub configuration a bit by pressing :kbd:`e` (for edit) and + remove the ``i915.modeset=0 video=efifb:off`` parameters at the end of + the multiboot2 grub command: + + .. code-block:: console + :emphasize-lines: 8 + + setparams 'ACRN multiboot2 ' + + load_video + insmod gzio + insmod part_gpt + insmod ext2 + search --no-floppy --fs-uuid --set $uuid + multiboot2 /boot/acrn.industry.nuc7i7dnb.bin root=PARTUUID="06d5265d-863a-4bc0-b469-66b5e6b8a9cb" i915.modeset=0 video=efifb:off + module2 /boot/vmlinuz-5.4.43.PKT-200203T060100Z Linux_bzImage + + Then press :kbd:`F10` to continue booting + +.. rst-class:: numbered-step + +Verify ACRN is running +********************** + +After the system boots, you can verify ACRN was detected and is running +by looking at the dmesg log: + +.. code-block:: console + :emphasize-lines: 3 + + acrn@acrn-NUC:~$ dmesg | grep -i acrn + [ 0.000000] Linux version 5.4.43-PKT-200203T060100Z (root@acrn-NUC7i7DNHE) (gcc version 7.5.0 (Ubuntu 7.5.0-3ubuntu1~18.04)) #1 SMP PREEMPT Thu Jul 16 16:33:58 CST 2020 + [ 0.000000] Hypervisor detected: ACRN + [ 2.413796] ACRNTrace: Initialized acrn trace module with 4 cpu + [ 2.413883] ACRN HVLog: Failed to init last hvlog devs, errno -19 + [ 2.413884] ACRN HVLog: Initialized hvlog module with 4 cpu -install command +.. comment -sudo dpkg -i acrn_deb_package.deb - -sudo dpkg -i acrn_kernel_deb_package.deb - - -uninstall - -sudo dpkg -r acrn-package - -sudo dpkg -r acrn-kernel-package - -4.python3 compile_iasl.py -========================= -this scriptrs is help compile iasl and cp to /usr/sbin + 4.python3 compile_iasl.py + ========================= + this scriptrs is help compile iasl and cp to /usr/sbin diff --git a/misc/packaging/release.json b/misc/packaging/release.json index 74a6ecb76..ec0df81fb 100644 --- a/misc/packaging/release.json +++ b/misc/packaging/release.json @@ -1,38 +1,68 @@ { - "//":"release ubuntu as sos verion", - "install_package":"true", - "gcc_version":"7.3.0", - "binutils":"2.27", - "//":"acrn-hypervisor config", - "build_acrn":"true", - "sync_acrn_code":"true", - "acrn_repo":"https://github.com/projectacrn/acrn-hypervisor.git", - "release_version":"remotes/origin/release_2.0", - "acrn_deb_package":"true", - "install_acrn_deb":"false", - "build_cmd": - { - "scenario": - { - "industry":"true", - "hybrid":"true", - "logical_partition":"true" + "//":"Configuration for packaging ACRN and Ubuntu for simple installation", - }, - "board": - { - "nuc7i7dnb":"true", - "whl-ipc-i5":"true" - }, - "release":"0" - }, - "//":"kernel config", - "build_acrn_kernel":"true", - "sync_acrn_kernel_code":"true", - "kernel_release_version":"remotes/origin/release_2.0", - "sos_kernel_repo":"https://github.com/projectacrn/acrn-kernel.git", - "acrn_kernel_deb_package":"true", - "install_acrn_kernel_deb":"false", - "//":"misc", - "auto_reboot":"false" + "//":"if true, the script will first install all needed apps and libraries and verify gcc and binutils versions ", + "install_package":"true", + "gcc_version":"7.3.0", + "binutils":"2.27", + + "//":"acrn-hypervisor config -------------------------------------", + + "//":"if true, uses make to build ACRN from source for the scenarios and boards specified by build_cmd below", + "build_acrn":"true", + + "//":"if true, (and build_acrn is true) clone a local copy of the specified release version of the ACRN hypervisor repo", + "//":"if false, assume the repo's local copy is OK", + "sync_acrn_code":"true", + "acrn_repo":"https://github.com/projectacrn/acrn-hypervisor.git", + "release_version":"remotes/origin/release_2.0", + + "//":"if true, build the acrn_deb_package.deb with the ACRN hypervisor and tools", + "//":"(if build_acrn is false, the package contents won't be recompiled before packaging)", + "acrn_deb_package":"true", + + "//":"if true, install the acrn_deb package locally after it's built", + "//":"(normally the package is copied to the target and installed there, so default is false)", + "install_acrn_deb":"false", + + "//":"This is the list of scenario and board combinations that will be built into the package", + "//":"(each scenario for each board) use release=0 for debug build, and 1 for production build", + "build_cmd": + { + "scenario": + { + "industry":"true", + "hybrid":"true", + "logical_partition":"true" + }, + "board": + { + "nuc7i7dnb":"true", + "whl-ipc-i5":"true" + }, + "release":"0" + }, + + "//":"kernel config ----------------------------------------------", + + "//":"if true, uses make to build the ACRN-patched kernel from source", + "build_acrn_kernel":"true", + + "//":"if true, (and build_acrn_kernel is true) clone a local copy of the specified release version of the ACRN kernel repo", + "//":"if false, assume the repo's local copy is OK", + "sync_acrn_kernel_code":"true", + "kernel_release_version":"remotes/origin/release_2.0", + "sos_kernel_repo":"https://github.com/projectacrn/acrn-kernel.git", + + "//":"if true, build the acrn_kernel_deb_package.deb with the ACRN kernel", + "//":"(if build_acrn_kernel is false, the package contents won't be recompiled before packaging)", + "acrn_kernel_deb_package":"true", + + "//":"if true, install the acrn_kernel_deb package locally after it's built", + "//":"(normally the package is copied to the target and installed there, so default is false)", + "install_acrn_kernel_deb":"false", + + "//":"misc -------------------------------------------------------", + + "auto_reboot":"false" }