Project ACRN™
1.5
Project ACRN
v: 1.5
Document Versions
latest
1.5
1.4
1.3
1.2
1.1
1.0
projectacrn.org links
Project Home
Wiki
Documentation Home
Learn about ACRN
Introduction to Project ACRN
ACRN High-Level Architecture
Usage Scenarios
Automotive Application Scenarios
Industrial Workload Consolidation
Best Known Configurations
SDC scenario with two VMs
SDC scenario with four VMs
Industry scenario without a safety VM
Industry scenario with a safety VM
Logical Partitioning scenario
Licensing
ACRN Device Model, Service VM, and User VM
Boot Sequence
De-privilege boot mode
Direct boot mode
ACRN Hypervisor Architecture
ACRN Device Model Architecture
Device pass through
Hardware support for device passthrough
Hypervisor support for device passthrough
ACRN I/O mediator
Virtio framework architecture
Try using ACRN
Supported Hardware
Minimum System Requirements for Installing ACRN
Minimum Requirements for Processor
Known Limitations
Verified Platforms According to ACRN Usage
Verified Hardware Specifications Detail
Build ACRN from Source
Introduction
Step 1: Install build tools and dependencies
Step 2: Get the ACRN hypervisor source code
Step 3: Build with the ACRN scenario
Step 4: Build the hypervisor configuration
Modify the hypervisor configuration
Step 5: Build the hypervisor, device model, and tools
Getting Started Guide for ACRN Industry Scenario
Verified version
Prerequisites
Hardware Setup
Set up the ACRN Hypervisor for industry scenario
Use the pre-installed industry ACRN hypervisor
Use the ACRN industry out-of-the-box image
Install and launch the Preempt-RT VM
RT Performance Test
Cyclictest introduction
Pre-Configurations
Run cyclictest
Troubleshooting
Use serial port on KBL NUC
EFI image doesn’t exist
Enabling the network on RTVM
Develop using ACRN
Configuration Tools
ACRN Configuration Tool
Introduction
ACRN configuration XMLs
Configuration tool workflow
Use the ACRN configuration app
Configuration Tutorials
Getting started guide for UP2 board
Hardware setup
Software setup
Running the hypervisor
Increasing the User OS disk size
Increase the virtual disk size
Resize the
rootfs
partition
Resize the filesystem
How to sign binaries of the Clear Linux image
Prerequisites
Steps to sign the binaries of the Clear Linux image
Using a static IP address
ACRN Network Setup
Setting up the static IP address
Activate the new configuration
ACRN Debugging Tools
ACRN Console Command
An example
ACRN Log
ACRN Trace
Using partition mode on NUC
Prerequisites
Update kernel image and modules of Pre-launched VM
Update ACRN hypervisor Image
Update Ubuntu GRUB to Boot hypervisor and Load Kernel Image
Logical Partition Scenario Startup Checking
Using partition mode on UP2
Prerequisites
Build kernel and modules for partition mode UOS
Enable partition mode in ACRN hypervisor
Switch between privileged VMs
Launch Two User VMs on NUC using SDC2 Scenario
ACRN Service VM Setup
Re-build ACRN UEFI Executable
Launch User VMs with predefined UUIDs
Using Hybrid Mode on the NUC
Prerequisites
Update Ubuntu GRUB
Hybrid Scenario Startup Checking
Real-Time (RT) Performance Analysis on ACRN
vmexit
analysis for ACRN RT performance
Collecting Performance Monitoring Counters data
Using SDC Mode on the NUC
Validated Version
Software Setup
Secure Boot enabling for Clear Linux User VM
Prerequisites
Validated versions
Prepare keys (PK/KEK/DB)
Sign the Clear Linux image
Boot Clear Linux signed image
Building ACRN in Docker
Install Docker
Get the Docker Image
Build ACRN from Source in Docker
Build the ACRN Service VM Kernel in Docker
Build the ACRN User VM PREEMPT_RT Kernel in Docker
Build the ACRN documentation
Install ACRN Out-of-the-box
Set up a Build Environment
Generate a Service VM image
Generate a User VM Preempt-RT image
Run Kata Containers on a Service VM
Pre-Requisites
Configure Kata on ACRN
User VM Tutorials
Using AGL as the User OS
Introduction to AGL
Steps for using AGL as the UOS
Enable the AGL display
Follow up
Running AGL as VMs
Hardware Setup
Software Setup
Using Celadon as the User OS
Prerequisites
Build Celadon from source
Steps for Using Celadon as the User OS
Building UOS from Clear Linux OS
Build UOS image in Clear Linux OS
Start the User OS (UOS)
Using VxWorks* as User OS
Steps for Using VxWorks as User OS
Using Windows as Guest VM on ACRN
Verified version
Hardware setup
ACRN Service VM Setup
Setup for Using Windows as Guest VM
ACRN Windows verified feature list
Known Limitations
Device configurations of acrn-dm command line
Secure boot enabling
Activate Windows 10
References
Using Zephyr as User OS
Introduction to Zephyr
Steps for Using Zephyr as User OS
Running Debian as the User VM
Prerequisites
Build the Debian KVM Image
Launch the Debian Image as the User VM
Enable the ttyS0 Console on the Debian VM
Running Ubuntu as the User VM
Prerequisites
Build the Ubuntu KVM Image
Launch the Ubuntu Image as the User VM
Enable the Ubuntu Console instead of the User Interface
Service VM Tutorials
Using Ubuntu as the Service OS
Install Ubuntu (natively)
Install ACRN
Install the Service OS kernel
Prepare the User OS (UOS)
Start the User OS (UOS)
Enabling network sharing
Enabling USB keyboard and mouse
Running Debian as the Service VM
Prerequisites
Validated Versions
Install ACRN on the Debian VM
Enable ACRN Features
Enable QoS based on runC container
What is QoS
What is runC container
ACRN-DM QoS architecture
ACRN-QoS CPU utilization example
How to use ACRN-DM QoS
How to enable OVS in ACRN
What is OVS
Why OVS
How to enable OVS in ACRN
How to use OVS bridge
Example for VLAN network based on OVS in ACRN
Real time VM application design guidelines
Run RTVM with dedicated resources/devices
RTVM with virtio PMD (Polling Mode Driver) for I/O sharing
RTVM with HV Emulated Device
DM emulated device (Except PMD)
SGX Virtualization
High Level ACRN SGX Virtualization Design
Enable SGX support for Guest
SGX Capability Exposure
Enclave System Function Handling
Other VMExit Control
Future Development
vUART Configuration
Introduction
Console enable list
How to configure a console port
How to configure a communication port
Communication vUART enable list
Launch script
Test the communication port
vUART design
COM port configurations for Post-Launched VMs
GPU Passthrough on Skylake NUC
Hardware platform
Software Configuration
Software Setup
Using CAT on UP2
CAT Support on ACRN
Tuning CAT in HV debug shell
Configure CAT for VM with VM Configuration
Using SBL on UP2 Board
Prerequisites
Build SBL
Flash SBL on the UP2
Build ACRN for UP2
Download and install flash tool
SOS and LaaG Installation
Boot to SOS
Launch UOS
Trusty and Security Services in ACRN
Trusty Architecture
Trusty Services
Trusty in ACRN
How to enable secure boot for Windows
Generate Platform Key (PK)
Download KEK and DB from Microsoft
Compile OVMF with secure boot support
Use QEMU to inject secure boot keys into OVMF
Platform S5 Enable Guide
Introduction
S5 Architecture
Enable S5
How to test
ACRN CPU Sharing
Introduction
Scheduling Framework
vCPU affinity
Thread object state
Scheduler
Scheduler configuration
Example
Contribute to ACRN
Design Guides
ACRN Hypervisor: Modular Design
Overview
Principles
Architecture
References
High-Level Design Guides
Overview
Hypervisor
Device Model
Emulated Devices
Virtio Devices
Power Management
Tracing and Logging
Virtual Bootloader
Security
Software Design Guidelines
Error Detection and Error Handling
Module Level Configuration Design Guidelines
References
GVT-g Enabling and Porting Guide
Introduction
Purpose of this document
Overall Components
Core scenario interaction sequences
API details
Trusty TEE
Introduction
Trusty Architecture
Trusty specific Hypercalls
Trusty Boot flow
EPT Hierarchy
L1 Terminal Fault Mitigation
Overview
L1TF Problem in ACRN
L1TF Mitigation in ACRN
Mitigation Recommendations
Mitigation Status
VBS-K Framework Virtualization Overhead Analysis
Introduction
Architecture of VIRTIO-ECHO
Virtualization Overhead Analysis
Conclusion
Contributing Guides
Contribution Guidelines
Licensing
Developer Certification of Origin (DCO)
Prerequisites
Repository layout
Submitting Issues
Contribution Tools and Git Setup
Coding Style
Contribution Workflow
Commit Guidelines
Coding Guidelines
C Programming Language Coding Guidelines
Assembly Language Coding Guidelines
Documentation Guidelines
Headings
Content Highlighting
Lists
Multi-column lists
File names and Commands
Internal Cross-Reference Linking
Non-ASCII Characters
Code and Command Examples
Tabs, spaces, and indenting
Drawings
Drawings using graphviz
Simple directed graph
Adding edge labels
Tables
Finite-State Machine
ACRN documentation generation
Documentation overview
Set up the documentation working folders
Installing the documentation tools
Documentation presentation theme
Running the documentation processors
Publishing content
Document Versioning
Filtering expected warnings
Tools
ACRN-Crashlog
Introduction
Building
Installing
Enabling/Disabling
Usage
Source Code
acrnprobe
Description
Usage
Architecture
Source files
Configuration files
acrnprobe Configuration
Description
Layout
Properties of group members
Crash tree in acrnprobe
Sections
usercrash
Description
Design
Usage
Source Code
acrnlog
Description
Usage
Build and Install
acrntrace
Description
Usage
Build and Install
acrnctl and acrnd
Description
acrnd
Build and Install
Developer references
API Documentation
Hypercall APIs
Device Model APIs
ACRN GVT-g APIs
Core Driver Infrastructure
VHM APIs called from AcrnGT
AcrnGT mediated pass-through (MPT) interface
GVT-g intel_gvt_ops interface
AcrnGT sysfs interface
Configuration Symbol Reference
Introduction
Supported Options
ACRN Shell Commands
Command examples
vm_list
vcpu_list
vcpu_dumpreg
dump_host_mem
dump_guest_mem
vm_console
vioapic
dump_ioapic
pt
int
cpuid
rdmsr
wrmsr
ACRN Kernel Parameters
Generic kernel parameters
Intel GVT-g (AcrnGT) Parameters
GVT-g (AcrnGT) Kernel Options details
i915.domain_scaler_owner
i915.enable_hangcheck
Device Model Parameters
Release Notes
ACRN v1.5 (Jan 2020)
Version 1.5 major features
What’s New in v1.5
Document updates
Fixed Issues Details
Known Issues
Change Log
ACRN v1.4 (Oct 2019)
Version 1.4 major features
What’s New in v1.4
Document updates
Security Vulnerabilities
New Features Details
Fixed Issues Details
Known Issues
Change Log
ACRN v1.3 (Sep 2019)
Version 1.3 major features
What’s New in v1.3
Document updates
New Features Details
Fixed Issues Details
Known Issues
Change Log
ACRN v1.2 (Aug 2019)
Version 1.2 major features
What’s New in v1.2
Document updates
New Features Details
Fixed Issues Details
Known Issues
Change Log
ACRN v1.1 (June 2019)
Version 1.1 major features
Hybrid Mode Introduced
Support for new guest Operating Systems
Document updates
New Features Details
Fixed Issues Details
Known Issues
Change Log
ACRN v1.0.2 (November 2019)
Change Log in v1.0.2 since v1.0.1
ACRN v1.0.1 (July 2019)
Change Log in version 1.0.1 since version 1.0
ACRN v1.0 (May 2019)
Version 1.0 major features
Hardware Support
APL UP2 board with SBL firmware
Enable post-launched RTVM support for real-time UOS in ACRN
Enable cache QOS with CAT
Enable QoS based on runC container
S5 support for RTVM
OVMF support initial patches merged in ACRN
Support ACPI power key mediator
VT-x, VT-d
PIC/IOAPIC/MSI/MSI-X/PCI/LAPIC
Ethernet
Mass Storage
USB (xDCI)
USB Mediator (xHCI)
Wi-Fi
IPU (MIPI CSI-2, HDMI-in)
Bluetooth
GVT-g for ACRN
GPU - Preemption
GPU - display surface sharing via Hyper DMA
Virtio standard is supported
Device pass-through support
GPIO virtualization
New ACRN tools
Document updates
New Features Details
Fixed Issues Details
Known Issues
Change Log
ACRN v0.8 (Apr 2019)
Version 0.8 new features
GPIO virtualization
Enable QoS based on runC container
S5 support for RTVM
Document updates
New Features Details
Fixed Issues Details
Known Issues
Change Log
ACRN v0.7 (Mar 2019)
Version 0.7 new features
Enable cache QOS with CAT
Support ACPI power key mediator
Document updates
New Features Details
Fixed Issues Details
Known Issues
Change Log
ACRN v0.6 (Feb 2019)
Version 0.6 new features
Fixed Issues
Known Issues
Change Log
ACRN v0.5 (Jan 2019)
Version 0.5 new features
Fixed Issues
Known Issues
Change Log
ACRN v0.4 (Dec 2018)
Version 0.4 new features
Fixed Issues
Known Issues
Change Log
ACRN v0.3 (Nov 2018)
Version 0.3 new features
Fixed Issues
Known Issues
Change Log
ACRN v0.2 (Sep 2018)
Version 0.2 new features
VT-x, VT-d
PIC/IOAPIC/MSI/MSI-X/PCI/LAPIC
Ethernet
Storage (eMMC)
USB (xDCI)
USB Mediator (xHCI and DRD)
CSME
WiFi
IPU (MIPI-CS2, HDMI-in)
Bluetooth
GPU - Preemption
GPU - display surface sharing via Hyper DMA
S3
Fixed Issues
Known Issues
Change Log
ACRN v0.1 (July 2018)
Version 0.1 new features
Hardware Support
GVT-g for ACRN
Virtio standard is supported
Device pass-through support
Hypervisor configuration
New ACRN tools
Known Issues
Change Log
Security Advisory
FAQ
What hardware does ACRN support?
Clear Linux* OS fails to boot on my NUC
How do I configure ACRN’s memory size?
How to modify the default display output for a User VM?
Why does ACRN need to know how much RAM the system has?
How to build ACRN on Fedora 29?
Project ACRN™
Docs
»
Contribute to ACRN
»
High-Level Design Guides
»
Virtual Slim-Bootloader high-level design
Virtual Slim-Bootloader high-level design
¶