From 2c7d9719650a4439fdf727f9f8c4b54c3611cee3 Mon Sep 17 00:00:00 2001 From: huyang531 Date: Sat, 23 Mar 2024 21:37:02 -0400 Subject: [PATCH 1/4] docs/concepts: Fix a few typos in build-process.mdx and index.mdx --- content/docs/concepts/build-process.mdx | 2 +- content/docs/concepts/index.mdx | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/content/docs/concepts/build-process.mdx b/content/docs/concepts/build-process.mdx index ade4eb21..18b4e59e 100644 --- a/content/docs/concepts/build-process.mdx +++ b/content/docs/concepts/build-process.mdx @@ -5,7 +5,7 @@ description: | Unikraft's build system which generate a unikernel. --- -Unikraft is designed to build ultra-lightweight VM images. For that matter, the +Unikraft is designed to build ultra-lightweight VM images. For that matter, the build system is designed to take only the absolute necessary pieces of code and bind them togheter. diff --git a/content/docs/concepts/index.mdx b/content/docs/concepts/index.mdx index 67cd204a..b381b1b5 100644 --- a/content/docs/concepts/index.mdx +++ b/content/docs/concepts/index.mdx @@ -39,7 +39,7 @@ Unikernels are specifically designed for use in cloud environments. In most production systems often the standard unit of isolation is the VM since this provides the greatest degree of security for the enclosed application(s). Its isolation is made possible directly by hardware primitives instead of OS-level -(software) primitives. However, a fully virtualized traditional VMs is too +(software) primitives. However, a fully virtualized traditional VM is too heavy for most applications which has led to the container-based model. Naturally, the evolution of running applications in the cloud has led to the model where containers are deployed within VMs due to the properties of each @@ -97,6 +97,7 @@ To meet the needs of a large variety of different use cases, KPIs and contexts, configuration of library components allow users to tune specific attributes to their liking. This ability to configure all parts of the unikernel is first-class in Unikraft and enables developers to develop the best-in-class +applications. In Unikraft, this system is enabled by a custom port of [Linux's KConfig system](#) which allows users to quickly and easily pick and choose which From fecda7ef2c688e1019250e0319b2d94620458b3b Mon Sep 17 00:00:00 2001 From: Yang Hu Date: Sun, 16 Jun 2024 21:23:57 -0400 Subject: [PATCH 2/4] guides/internals: add notes about hardware acceleration with KVM for random number generating since v0.17.0 Signed-off-by: Yang Hu --- content/guides/internals.mdx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/content/guides/internals.mdx b/content/guides/internals.mdx index eba0f9f4..0c1f27d4 100644 --- a/content/guides/internals.mdx +++ b/content/guides/internals.mdx @@ -163,11 +163,18 @@ Notice that each line in `make`'s output consists of an operation in the build p Now that the unikernel image has been sucessfully generated, we can finally run it using the QEMU Virtual Machine Monitor: ```console -$ qemu-system-x86_64 -kernel build/helloworld_qemu-x86_64 -nographic +$ qemu-system-x86_64 -kernel workdir/build/helloworld_qemu-x86_64 -nographic -enable-kvm -cpu host ``` The `-kernel` option is used for indicating the image to be booted by the machine, while the `-nographic` option is simply for using QEMU as a command-line program by redirecting all output to the terminal. +Since [Unikraft v0.17.0 Calypso](https://github.com/unikraft/unikraft/releases/tag/RELEASE-0.17.0), random number generation is reliant on CPU support. This means that, when using QEMU, one of two options must be enabled: + +- You are using QEMU >= 8.0 +- You are using hardware acceleration, with KVM + +This is why we use `-enable-kvm` and `-cpu host` flags to explictly enable them. If you are running on other platforms, please remove them. + ```console SeaBIOS (version Arch Linux 1.16.2-1-1) From a6be237c1a47f15ab16a49a191877d41d77d18bc Mon Sep 17 00:00:00 2001 From: huyang531 Date: Thu, 11 Jul 2024 14:13:53 +0300 Subject: [PATCH 3/4] fix(guide): Fix minor formatting issues Signed-off-by: huyang531 --- content/docs/concepts/build-process.mdx | 24 +++++++++++++----------- content/docs/concepts/index.mdx | 9 +++------ content/guides/internals.mdx | 15 ++++++++++++--- 3 files changed, 28 insertions(+), 20 deletions(-) diff --git a/content/docs/concepts/build-process.mdx b/content/docs/concepts/build-process.mdx index 18b4e59e..deb481bf 100644 --- a/content/docs/concepts/build-process.mdx +++ b/content/docs/concepts/build-process.mdx @@ -25,21 +25,23 @@ The lifecycle of the construction of a Unikraft unikernel includes several distinct steps: 1. Configuring the Unikraft unikernel application with compile-time options; -2. Fetching and preparing the source code for external libraries; -3. Compiling the libraries and the core Unikraft code; -4. Linking the final unikernel image. +1. Fetching and preparing the source code for external libraries; +1. Compiling the libraries and the core Unikraft code; +1. Linking the final unikernel image. ## GNU Make-based build system Unikraft is a configurable operating system, where each component can be -modified, configured, according to the user’s needs. This configuration is done -using a version of Kconfig, through the Config.uk files. In these files, options -are added to enable libraries, applications and different components of the -Unikraft core. The user can then apply those configuration options, using make +modified, configured, according to the user’s needs. +This configuration is done using a version of Kconfig, through the Config.uk + files. +In these files, options are added to enable libraries, applications and +different components of the Unikraft core. +The user can then apply those configuration options, using make menuconfig, which generates an internal configuration file that can be -understood by the build system, .config. Once configured, the Unikraft image can -be built, using make, and run, using the appropriate method (Linux ELF loader, -qemu-kvm, xen, others). +understood by the build system, .config +. Once configured, the Unikraft image can be built, using make, and run, +using the appropriate method (Linux ELF loader, qemu-kvm, xen, others). \ No newline at end of file +/> diff --git a/content/docs/concepts/index.mdx b/content/docs/concepts/index.mdx index b381b1b5..80267926 100644 --- a/content/docs/concepts/index.mdx +++ b/content/docs/concepts/index.mdx @@ -71,7 +71,6 @@ of an Ubuntu VM), Containers and Unikernels, represented by Unikraft: | **Security** | Very secure | Least secure of the 3 | Very secure | | **Features** | Everything you could think of | Depends on the needs | Only the absolute necessary | - ## Componenization At the heart of the unikernel model lies with the collection of composable, @@ -90,21 +89,19 @@ pre-existing libraries such as OpenSSL. > Read more about [Unikraft's modular > architecture](/docs/concepts/architecture). - ## Configurability To meet the needs of a large variety of different use cases, KPIs and contexts, configuration of library components allow users to tune specific attributes to their liking. This ability to configure all parts of the unikernel is -first-class in Unikraft and enables developers to develop the best-in-class +first-class in Unikraft and enables developers to develop the best-in-class applications. -In Unikraft, this system is enabled by a custom port of [Linux's KConfig -system](#) which allows users to quickly and easily pick and choose which +In Unikraft, this system is enabled by a custom port of Linux's KConfig +system which allows users to quickly and easily pick and choose which libraries to include in the build process, as well as to configure options for each of them, where available. - ## Tooling and Integrations The core of Unikraft is a suite of tools which aid in the creation of the final diff --git a/content/guides/internals.mdx b/content/guides/internals.mdx index 0c1f27d4..acc8af7d 100644 --- a/content/guides/internals.mdx +++ b/content/guides/internals.mdx @@ -156,6 +156,7 @@ The process should end with the following output: GZ helloworld_qemu-x86_64.gz make[1]: Leaving directory '/home/X/workdir/helloworld/workdir/unikraft' ``` + Notice that each line in `make`'s output consists of an operation in the build process (i.e compiling, linking, symbol striping etc.) and a corresponding generated file. ### Running @@ -173,7 +174,8 @@ Since [Unikraft v0.17.0 Calypso](https://github.com/unikraft/unikraft/releases/t - You are using QEMU >= 8.0 - You are using hardware acceleration, with KVM -This is why we use `-enable-kvm` and `-cpu host` flags to explictly enable them. If you are running on other platforms, please remove them. +This is why we use `-enable-kvm` and `-cpu host` flags to explictly enable them. +If you are running on other platforms, consider removing them. ```console SeaBIOS (version Arch Linux 1.16.2-1-1) @@ -212,19 +214,24 @@ When you exit the menu, you will most likely see this warning message: *** This is to ensure that the new setting is applied *** to every compilation unit. ``` + This is a very good recommandation and you'll use it a lot when configuring and building applications - so make sure to run ```console $ make properclean ``` -...followed by +. +. +.followed by ```console $ make -j$(nproc) ``` -...to finally build an ARM64 unikernel. +. +. +.to finally build an ARM64 unikernel. Since we are targeting a different architecture, we have to use QEMU to emulate an ARM64 CPU: ```console @@ -251,6 +258,7 @@ oOo oOO| | | | | (| | | (_) | _) :_ Hello world! Arguments: "helloworld" ``` + ### Enabling kernel logs We will now try to further configure our `helloworld` application. @@ -349,6 +357,7 @@ Arguments: "build/helloworld_qemu-x86_64" ``` You can notice that the debug logs prove to be quite useful: they include information such as timestamp, debugging level (warning, info, error etc.), internal library component (`libkvmpci`, `libukschedcoop` etc.) and the source file along with the line in it. + ### Enabling tests As an exercise, try to enable the `uktest` internal library from the configuration menu. From e0d8adf460efbd2c342a1636284e3bba89048e72 Mon Sep 17 00:00:00 2001 From: huyang531 Date: Thu, 11 Jul 2024 14:16:28 +0300 Subject: [PATCH 4/4] fix(guide): Fix minor formatting issue with internals.mdx Signed-off-by: huyang531 --- content/guides/internals.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/guides/internals.mdx b/content/guides/internals.mdx index acc8af7d..8d6cab26 100644 --- a/content/guides/internals.mdx +++ b/content/guides/internals.mdx @@ -231,7 +231,8 @@ $ make -j$(nproc) . . -.to finally build an ARM64 unikernel. +. +to finally build an ARM64 unikernel. Since we are targeting a different architecture, we have to use QEMU to emulate an ARM64 CPU: ```console