- Description:
- Firecracker with the chroot.dev fixes, branch chroot
- Last Change:
- Clone URL:
ssh://anon@got.v6.chroot.run/firecracker
- ED25519:
SHA256:7587EKj+viWIfWGzPGNqUFSdFEh83CZFaqnwaoNmcNc
Commit Briefs
acpi: Add _OSC method to the host bridge to grant the OS PCIe HP control (ilstam-hotplug-1)
Add an _OSC method to the host bridge. This can be used by the OS to request it's granted control of certain capabilities (PCIe hotplug, power management events, etc). Otherwise the platform keeps control of them. Grant whatever the guest asks for by returning the capabilities buffer unchanged. Granting control of features Firecracker does not implement is harmless. The guest only drives a feature if it also finds the corresponding PCI capability. Signed-off-by: Ilias Stamatis <ilstam@amazon.com>
fdt: Advertise PCI bus range
The FDT advertises a single PCI bus to the guest. Change this to advertise the full range of buses present in the system. Signed-off-by: Ilias Stamatis <ilstam@amazon.com>
acpi: Advertise bus ranges in MCFG and _CRS
Two bus ranges are advertised to the guest via ACPI tables and both describe bus 0 only. Subsequent patches will extend the bus topology so secondary buses need to be advertised too. Make the MCFG ECAM entry cover every bus a PCI segment can possibly have, and add the full bus range of present buses in the host bridge's _CRS. Signed-off-by: Ilias Stamatis <ilstam@amazon.com>
pci: Resize the ECAM region from 1 to 32 buses
Until now PCI_MMIO_CONFIG_SIZE_PER_SEGMENT was meant to cover every device and function in a single bus because it was assumed that there's a single PCI bus in the system. Since we are going to expand the topology to support up to 32 buses this needs to be updated. Rename PCI_MMIO_CONFIG_SIZE_PER_SEGMENT to PCI_MMIO_CONFIG_SIZE_PER_BUS which is a more accurate name and move the constant to pci/bus.rs instead of repeating its definition per arch. And add a new PCI_MMIO_CONFIG_SIZE_PER_SEGMENT that represents the ECAM space for 32 buses. The ECAM regions grows from 1 MiB to 32 MiB which is 's still well inside the 256 MiB PCI_MMCONFIG_SIZE window which could be used to cover every possible BDF (256 buses). The test_mmio_bus() test used to access the entire 1MiB ECAM region, but that's not possible after growing the ECAM region to 32 MiB since the stack is not large enough to accommodate such a large local variable. Adjust the test to instead check that the beginning and end of the ECAM region can be accessed, whereas accessing just before or just after it fails. Signed-off-by: Ilias Stamatis <ilstam@amazon.com>
pci: Support multi-bus configuration accesses
Today Firecracker presents a single PCI bus to the guest, with no Type 1 devices other than the host bridge itself. Virtio devices appear as Root Complex Integrated Endpoints attached directly to the host bridge, on bus 0. Native PCIe hot-plug needs root ports, and each root port starts a secondary bus, so configuration cycles have to be able to reach buses other than 0. Introduce PciBuses holding the buses a segment has; the root bus plus one secondary bus per root port. No visible change for the guest at this point, nothing creates root ports and secondary buses yet. Signed-off-by: Ilias Stamatis <ilstam@amazon.com>
test(api): run test_send_ctrl_alt_del on aarch64 (main)
Update the API test now that SendCtrlAltDel is accepted on aarch64 and the CI guest kernels have been rebuilt with the gpio-keys config. The aarch64 press is consumed by systemd-logind, which only works on the AL23 rootfs shipped with the 6.1 kernels and needs a `rw` rootfs to trigger the reboot, so those two dimensions are pinned on aarch64 only; x86_64 goes through the i8042 device and keeps its full guest kernel and rootfs coverage. For the same reason the `kernel` mode, which shortcuts through /proc/sys/kernel/ctrl-alt-del, stays x86_64 only: aarch64 delivers the press as a KEY_POWER input event that the sysctl does not act on. Also add a regression test for issuing the action while the microVM is paused: the guest cannot observe the request until its vCPUs run again, so it has to stay pending across the pause instead of being delivered into a stopped guest and dropped. Kept as a separate commit so it can be easily dropped or updated. Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Assisted-by: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
docs(changelog): add entry for aarch64 SendCtrlAltDel
Record under Added that SendCtrlAltDel is now supported on aarch64, where it presses a virtual power button on a PL061 GPIO controller exposed to the guest as gpio-keys. Snapshot version 12.0.0 shipped in v1.17.0, so persisting the new PL061 register state needs a bump to 13.0.0. The entry mentions it because it is a user-visible compatibility change. Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
docs: document aarch64 SendCtrlAltDel graceful shutdown
Describe the aarch64 behaviour of the SendCtrlAltDel action (a virtual power button via the PL061 gpio-keys device) in the actions and device-api docs, including that the press is held until the guest observes it and so survives a paused microVM and a snapshot. Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
feat(aarch64): support external graceful shutdown via SendCtrlAltDel
Until now `SendCtrlAltDel` was rejected with a 400 on aarch64 and there was no way to request a graceful shutdown of a microVM from the host. Fixes #2046. Attach the PL061 GPIO controller as an aarch64 MMIO platform device and describe a `gpio-keys` power button (KEY_POWER) in the FDT. `SendCtrlAltDel` is reused: on x86_64 it still injects CTRL+ALT+DEL through the i8042 device; on aarch64 it presses the virtual power button. A guest with the standard gpio-keys driver and a power-key consumer (e.g. systemd-logind, which defaults to HandlePowerKey=poweroff) then shuts down cleanly and Firecracker exits on the resulting KVM_SYSTEM_EVENT_SHUTDOWN. Details: - The press is latched by the device until the guest reads the line back, so the action returns immediately and a press issued while the microVM is `Paused` is delivered once it is resumed. This matches the x86_64 path, where the keystroke stays queued in the i8042 until the guest consumes it. - The PL061 register state, including a still-pending press, is saved and restored as part of the MMIO platform device state, so the power button keeps working on a restored microVM. Restoring replays the GSI reservation, so the legacy IRQ the device used cannot be handed out to another device. The added state changes the snapshot format, so the snapshot version goes from 12.0.0 to 13.0.0. - The gpio-keys kernel symbols are added to the shared CI kernel config so the guest can advertise the power key. - The controller is always attached, and takes one legacy GSI of its own, so the number of GSIs left for VirtIO devices drops by one: the aarch64 maximum goes from 92 to 91 devices. Assisted-by: Copilot <223556219+Copilot@users.noreply.github.com> Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
feat(aarch64): add PL061 GPIO controller device
Add a minimal PL061 GPIO controller modelled as an aarch64 MMIO device. It implements the core register bank (data with the address-masked aperture, direction, the interrupt sense, both-edges, event, mask, status and clear registers, and the PrimeCell identification registers) plus host-side input injection so higher layers can drive a virtual GPIO line. The interrupt line is modelled as edge-triggered to match Firecracker's plain KVM irqfd injection (no resample fd): a level-high line would never be de-asserted and the GIC would re-fire it after the guest EOIs, storming the host. Two behaviours are worth calling out: - A host-injected press is held until the guest reads the line back through the data aperture, at which point the device releases it and latches the falling edge. A press can therefore not be missed by a guest that is not currently running. - The level-sensitive part of GPIORIS tracks the line rather than being latched, so it clears once the level goes inactive and re-asserts after a GPIOIC write while the level is still active, as the TRM specifies. Arming GPIOIS/GPIOIBE/GPIOIEV re-evaluates the line instead of waiting for the next level change. The register state is serializable so it can be carried across snapshots, and a device rebuilt from a saved state re-raises any interrupt the guest had not acknowledged yet, since the restored device gets a fresh eventfd. Assisted-by: Copilot <223556219+Copilot@users.noreply.github.com> Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
Branches
Tree
README.md
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/images/fc_logo_full_transparent-bg_white-fg.png">
<source media="(prefers-color-scheme: light)" srcset="docs/images/fc_logo_full_transparent-bg.png">
<img alt="Firecracker Logo Title" width="750" src="docs/images/fc_logo_full_transparent-bg.png">
</picture>
Our mission is to enable secure, multi-tenant, minimal-overhead execution of
container and function workloads.
Read more about the Firecracker Charter [here](CHARTER.md).
## What is Firecracker?
Firecracker is an open source virtualization technology that is purpose-built
for creating and managing secure, multi-tenant container and function-based
services that provide serverless operational models. Firecracker runs workloads
in lightweight virtual machines, called microVMs, which combine the security and
isolation properties provided by hardware virtualization technology with the
speed and flexibility of containers.
## Overview
The main component of Firecracker is a virtual machine monitor (VMM) that uses
the Linux Kernel Virtual Machine (KVM) to create and run microVMs. Firecracker
has a minimalist design. It excludes unnecessary devices and guest-facing
functionality to reduce the memory footprint and attack surface area of each
microVM. This improves security, decreases the startup time, and increases
hardware utilization. Firecracker has also been integrated in container
runtimes, for example
[Kata Containers](https://github.com/kata-containers/kata-containers) and
[Flintlock](https://github.com/liquidmetal-dev/flintlock).
Firecracker was developed at Amazon Web Services to accelerate the speed and
efficiency of services like [AWS Lambda](https://aws.amazon.com/lambda/) and
[AWS Fargate](https://aws.amazon.com/fargate/). Firecracker is open sourced
under [Apache version 2.0](LICENSE).
To read more about Firecracker, check out
[firecracker-microvm.io](https://firecracker-microvm.github.io).
## Getting Started
To get started with Firecracker, download the latest
[release](https://github.com/firecracker-microvm/firecracker/releases) binaries
or build it from source.
You can build Firecracker on any Unix/Linux system that has Docker running (we
use a development container) and `bash` installed, as follows:
```bash
git clone https://github.com/firecracker-microvm/firecracker
cd firecracker
tools/devtool build
toolchain="$(uname -m)-unknown-linux-musl"
```
The Firecracker binary will be placed at
`build/cargo_target/${toolchain}/debug/firecracker`. For more information on
building, testing, and running Firecracker, go to the
[quickstart guide](docs/getting-started.md).
The overall security of Firecracker microVMs, including the ability to meet the
criteria for safe multi-tenant computing, depends on a well configured Linux
host operating system. A configuration that we believe meets this bar is
included in [the production host setup document](docs/prod-host-setup.md).
## Contributing
Firecracker is already running production workloads within AWS, but it's still
Day 1 on the journey guided by our [mission](CHARTER.md). There's a lot more to
build and we welcome all contributions.
To contribute to Firecracker, check out the development setup section in the
[getting started guide](docs/getting-started.md) and then the Firecracker
[contribution guidelines](CONTRIBUTING.md).
## Releases
New Firecracker versions are released via the GitHub repository
[releases](https://github.com/firecracker-microvm/firecracker/releases) page,
typically every two or three months. A history of changes is recorded in our
[changelog](CHANGELOG.md).
The Firecracker release policy is detailed [here](docs/RELEASE_POLICY.md).
## Design
Firecracker's overall architecture is described in
[the design document](docs/design.md).
## Features & Capabilities
Firecracker consists of a single micro Virtual Machine Manager process that
exposes an API endpoint to the host once started. The API is
[specified in OpenAPI format](src/firecracker/swagger/firecracker.yaml). Read
more about it in the [API docs](docs/api_requests).
The **API endpoint** can be used to:
- Configure the microvm by:
- Setting the number of vCPUs (the default is 1).
- Setting the memory size (the default is 128 MiB).
- Configuring a [CPU template](docs/cpu_templates/cpu-templates.md).
- Add one or more network interfaces to the microVM.
- Add one or more read-write or read-only disks to the microVM, each represented
by a file-backed block device.
- Trigger a block device re-scan while the guest is running. This enables the
guest OS to pick up size changes to the block device's backing file.
- Change the backing file for a block device, before or after the guest boots.
- Configure rate limiters for virtio devices which can limit the bandwidth,
operations per second, or both.
- Configure the logging and metric system.
- `[BETA]` Configure the data tree of the guest-facing metadata service. The
service is only available to the guest if this resource is configured.
- Add a [vsock socket](docs/vsock.md) to the microVM.
- Add a [entropy device](docs/entropy.md) to the microVM.
- Add a [pmem device](docs/pmem.md) to the microVM.
- Configure and manage [memory hotplugging](docs/memory-hotplug.md).
- `[Developer Preview]` [Hot-plug and hot-unplug](docs/device-hotplug.md) virtio
PCI devices while the VM is running.
- Start the microVM using a given kernel image, root file system, and boot
arguments.
- [x86_64 only] Stop the microVM.
**Built-in Capabilities**:
- Demand fault paging and CPU oversubscription enabled by default.
- Advanced, thread-specific seccomp filters for enhanced security.
- [Jailer](docs/jailer.md) process for starting Firecracker in production
scenarios; applies a cgroup/namespace isolation barrier and then drops
privileges.
## Tested platforms
We test all combinations of:
| Instance | Host OS & Kernel | Guest Rootfs | Guest Kernel |
| :------------------------------------------ | :---------------- | :----------- | :----------- |
| m5n.metal (Intel Cascade Lake) | al2 linux_5.10 | ubuntu 24.04 | linux_5.10 |
| m6i.metal (Intel Ice Lake) | al2023 linux_6.1 | | linux_6.1 |
| | al2023 linux_6.18 | | |
| m7i.metal-24xl (Intel Sapphire Rapids) | | | |
| m7i.metal-48xl (Intel Sapphire Rapids) | | | |
| **m8i.metal-48xl (Intel Granite Rapids)\*** | | | |
| **m8i.metal-96xl (Intel Granite Rapids)\*** | | | |
| m6a.metal (AMD Milan) | | | |
| m7a.metal-48xl (AMD Genoa) | | | |
| m6g.metal (Graviton 2) | | | |
| m7g.metal (Graviton 3) | | | |
| m8g.metal-24xl (Graviton 4) | | | |
| m8g.metal-48xl (Graviton 4) | | | |
| m9g.metal-48xl (Graviton 5) | | | |
**\***: We **only** support AWS EC2 8th Gen Intel (\*8i) instances using a 6.1
or 6.18 host kernel. This is due to poor kernel support for Granite Rapids CPUs
on 5.10.
## Known issues and Limitations
- The `pl031` RTC device on aarch64 does not support interrupts, so guest
programs which use an RTC alarm (e.g. `hwclock`) will not work.
## Performance
Firecracker's performance characteristics are listed as part of the
[specification documentation](SPECIFICATION.md). All specifications are a part
of our commitment to supporting container and function workloads in serverless
operational models, and are therefore enforced via continuous integration
testing.
## Policy for Security Disclosures
The security of Firecracker is our top priority. If you suspect you have
uncovered a vulnerability, contact us privately, as outlined in our
[security policy document](SECURITY.md); we will immediately prioritize your
disclosure.
## FAQ & Contact
Frequently asked questions are collected in our [FAQ doc](FAQ.md).
You can get in touch with the Firecracker community in the following ways:
- Security-related issues, see our [security policy document](SECURITY.md).
- Chat with us on our
[Slack workspace](https://join.slack.com/t/firecracker-microvm/shared_invite/zt-3v81btcpe-usCf8Qk7k1gUlSAEKKdYMg)
_Note: most of the maintainers are on a European time zone._
- Open a GitHub issue in this repository.
- Email the maintainers at
[firecracker-maintainers@amazon.com](mailto:firecracker-maintainers@amazon.com).
When communicating within the Firecracker community, please mind our
[code of conduct](CODE_OF_CONDUCT.md).