Project ACRN™
1.0
Project ACRN
v: 1.0
Document Versions
latest
0.8
0.7
0.6
0.5
projectacrn.org links
Project Home
Wiki
Introduction to Project ACRN
Automotive Use Case Example
Licensing
ACRN Device Model, Service OS, and User OS
Boot Sequence
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
Getting Started Guides
Getting started guide for Intel NUC
Hardware setup
Connecting to the serial port
Firmware update on the NUC
Software setup
Set up a Clear Linux Operating System
Use the script to set up ACRN automatically
Manual setup ACRN guide
Add the ACRN hypervisor to the EFI Partition
ACRN Network Bridge
Set up Reference UOS
Getting started guide for UP2 board
Hardware setup
Connecting to the serial port
Software setup
UP2 serial port setting
UP2 block device
Running the hypervisor
Build ACRN from Source
Install build tools and dependencies
Build the hypervisor, device model and tools
Configuring the hypervisor
Modify the hypervisor configurations
Create a new default configuration
Supported Hardware
Intel Apollo Lake NUC
Intel Kaby Lake NUC
UP Squared board
User Guides
ACRN Shell Commands
Command examples
vm_list
vcpu_list
vcpu_dumpreg
dumpmem
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
Tools
ACRN 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
acrnctl and acrnd
Description
Usage
acrnd
Build and Install
acrnlog
Description
Usage
Build and Install
acrntrace
Description
Usage
Build and Install
Developer Guides
High-Level Design Guides
Overview
ACRN Supported Use Cases
Hardware Requirements
ACRN Architecture
Hypervisor
SOS
UOS
Freedom From Interference
Boot Flow
Power Management
Hypervisor
Hypervisor Startup
CPU Virtualization
Memory management
I/O Emulation
IOC Virtualization
Physical Interrupt
Timer
Virtual Interrupt
VT-d
Device Passthrough
Partition mode
Power Management
Console, Shell, and vUART
Hypercall / VHM upcall
Compile-time configuration
Device Model
Configuration
DM Initialization
VHM
I/O Emulation in SOS
Device Emulation
ISA and PCI Emulation
ACPI Virtualization
PM in Device Model
Emulated Devices
USB Virtualization
UART virtualization
Watchdoc virtualization
Random device virtualization
GVT-g GPU Virtualization
Virtio Devices
Virtio introduction
Key Concepts
Virtio Frameworks
Virtio APIs
Supported Virtio Devices
VM Management
VM state
Scenarios of VM state change
VM State management
Power Management
P-state/C-state management
S3/S5
Tracing and Logging
Shared Buffer
ACRN Trace
ACRN Log
Virtual Bootloader
Security
Introduction
Background
ACRN High-Level Security Architecture
Developer Primer
Source Tree Structure
ACRN hypervisor source tree
ACRN Device Model source tree
ACRN Tools source tree
ACRN documentation source tree
CPU virtualization
Host GDT
Host IDT
Guest SMP Booting
VMX configuration
CPUID and Guest TSC calibration
RDTSC/RDTSCP
CR Register virtualization
MSR BITMAP
I/O BITMAP
Exceptions
Memory virtualization
Physical Memory Layout
PV (MMU) Memory Mapping in the Hypervisor
PV (MMU) Memory Mapping in VMs
Host-Guest (EPT) Memory Mapping
Graphic mediation
I/O emulation
Device Assignment Management
PIO/MMIO trap Flow
Virtual interrupt
Virtual LAPIC
Virtual IOAPIC
Virtual PIC
Virtual Interrupt Injection
VT-x and VT-d
Hypercall
Device emulation
Virtio Devices
Virtio-rnd
Virtio-blk
Virtio-net
Virtio-console
GVT-g Enabling and Porting Guide
Introduction
Purpose of this document
Overall Components
Core scenario interaction sequences
vGPU creation scenario
vGPU destroy scenario
vGPU pci configure space write scenario
pci configure space read scenario
GGTT read/write scenario
MMIO read/write scenario
PPGTT write protection page set/unset scenario
PPGTT write protection page write
API details
Trusty TEE
Introduction
Trusty Architecture
Trusty specific Hypercalls
Trusty Boot flow
EPT Hierarchy
Design
Benefit
API
L1 Terminal Fault Mitigation
Overview
L1TF Problem in ACRN
Guest -> hypervisor Attack
Guest -> guest Attack
Normal_world -> Secure_world Attack
Affected Processors
L1TF Mitigation in ACRN
L1D flush on VMENTRY
EPT Sanitization
Put Secret Data into Uncached Memory
L1D flush on World Switch
Core-based scheduling
Mitigation Recommendations
Mitigation Status
VBS-K Framework Virtualization Overhead Analysis
Introduction
Architecture of VIRTIO-ECHO
Virtualization Overhead Analysis
Conclusion
ACRN Hypervisor: Modular Design
Overview
Principles
Minimizing Cyclic Dependencies
Measuring Complexity
Architecture
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
Contributing to the project
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
Software Design Guidelines
Error Detection and Error Handling
Module Level Configuration Design Guidelines
References
Tutorials
Running AGL as VMs
Hardware setup
Connecting hardware
Software Setup
Service OS
Building ACRN kernel for AGL (UOS)
Setting up AGLs
Building UOS from Clear Linux OS
Build UOS image in Clear Linux OS
Start the User OS (UOS)
ACRN Debugging Tools
ACRN Console Command
An example
ACRN Log
Turn on the logging info
Set and grab log
ACRN Trace
Using Existing trace event id to analyze trace
Using Self-defined trace event id to analyze trace
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
Increasing the User OS disk size
Increase the virtual disk size
Resize the
rootfs
partition
Resize the filesystem
Using PREEMPT_RT-Linux for real-time UOS
GPU Passthrough on Skylake NUC
Hardware platform
Software Configuration
Software Setup
Using a static IP address
ACRN Network Setup
Setting up the static IP address
Activate the new configuration
Trusty and Security Services in ACRN
Trusty Architecture
Trusty Services
Keystore
Secure Storage (SS)
Trusty in ACRN
One-VM, Two-Worlds
Secure Storage Virtualization
References:
Using AGL as the User OS
Introduction to AGL
Steps for using AGL as the UOS
Enable the AGL display
Follow up
Using CAT on UP2
CAT Support on ACRN
Tuning CAT in HV debug shell
Configure CAT for VM with VM Configuration
Using partition mode on UP2
Prerequisites
Build kernel and modules for partition mode UOS
Enable partition mode in ACRN hypervisor
Switch between privileged VMs
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
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
Using Zephyr as User OS
Introduction to Zephyr
Steps for Using Zephyr as User OS
Release Notes
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
FAQ
What hardware does ACRN support?
Clear Linux* OS fails to boot on my NUC
How do I configure ACRN’s memory use?
How to modify the default display output for a UOS?
Why does ACRN need to know how much RAM the system has?
How to build ACRN on Fedora 29?
Project ACRN™
Docs
»
Developer Guides
»
High-Level Design Guides
»
Hypervisor high-level design
Hypervisor high-level design
¶
Hypervisor Startup
CPU Virtualization
Memory management
I/O Emulation
IOC Virtualization
Physical Interrupt
Timer
Virtual Interrupt
VT-d
Device Passthrough
Partition mode
Power Management
Console, Shell, and vUART
Hypercall / VHM upcall
Compile-time configuration