Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit b5a70a3

Browse files
committed
doc: add documentation on usage of PCI support
Add information in our Documentation regarding how users can enable PCI support for Firecracker microVMs and mention requirements for building the guest kernel, as well as the requirements for kernel command line parameters. Also, add an entry in the CHANGELOG mentioning the addition of PCI support. Signed-off-by: Babis Chalios <bchalios@amazon.es>
1 parent 92e936d commit b5a70a3

File tree

4 files changed

+84
-3
lines changed

4 files changed

+84
-3
lines changed

‎CHANGELOG.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,13 @@ and this project adheres to
5353
guest's serial console. Not configuring it means Firecracker will continue to
5454
print serial output to stdout. Similarly to the logger, this configuration is
5555
not persisted across snapshots.
56+
- [#5364](https://github.com/firecracker-microvm/firecracker/pull/5364): Added
57+
PCI support in Firecracker. PCI support is optional. Users can enable it
58+
passing the `--enable-pci` flag when launching the Firecracker process. When
59+
Firecracker process is launched with PCI support, it will create all VirtIO
60+
devices using a PCI VirtIO transport. If not enabled, Firecracker will use
61+
the MMIO transport instead.
62+
5663

5764
### Changed
5865

‎FAQ.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ Example of a kernel valid command line that enables the serial console (which
129129
goes in the `boot_args` field of the `/boot-source` Firecracker API resource):
130130

131131
```console
132-
console=ttyS0 reboot=k panic=1 pci=off nomodule
132+
console=ttyS0 reboot=k panic=1 nomodule
133133
```
134134

135135
### How can I configure multiple Ethernet devices through the kernel command line?

‎docs/getting-started.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -194,9 +194,15 @@ API_SOCKET="/tmp/firecracker.socket"
194194
sudo rm -f $API_SOCKET
195195

196196
# Run firecracker
197-
sudo ./firecracker --api-sock "${API_SOCKET}"
197+
sudo ./firecracker --api-sock "${API_SOCKET} --enable-pci"
198198
```
199199

200+
The `--enable-pci` flag instructs Firecracker to create all VirtIO devices using a PCI
201+
VirtIO transport. This flag is optional. If not passed, Firecracker will create devices using
202+
the legacy MMIO transport. We suggest that users enable the PCI transport, as it yields higher
203+
throughput and lower latency for VirtIO devices. For more information regarding guest kernel
204+
requirements for using PCI look at our [kernel policy documentation](./kernel-policy.md).
205+
200206
In a new terminal (do not close the 1st one):
201207

202208
```bash
@@ -240,7 +246,7 @@ sudo curl -X PUT --unix-socket "${API_SOCKET}" \
240246
"http://localhost/logger"
241247

242248
KERNEL="./$(ls vmlinux* | tail -1)"
243-
KERNEL_BOOT_ARGS="console=ttyS0 reboot=k panic=1 pci=off"
249+
KERNEL_BOOT_ARGS="console=ttyS0 reboot=k panic=1"
244250

245251
ARCH=$(uname -m)
246252

‎docs/kernel-policy.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,15 @@ The configuration items that may be relevant for Firecracker are:
6969
- use CPU RNG instructions (if present) to initialize RNG. Available for >=
7070
5.10
7171
- ACPI support - `CONFIG_ACPI` and `CONFIG_PCI`
72+
- PCI support:
73+
- `CONFIG_BLK_MQ_PCI`
74+
- `CONFIG_PCI`
75+
- `CONFIG_PCI_MMCONFIG`
76+
- `CONFIG_PCI_MSI`
77+
- `CONFIG_PCIEPORTBUS`
78+
- `CONFIG_VIRTIO_PCI`
79+
- `CONFIG_PCI_HOST_COMMON`
80+
- `CONFIG_PCI_HOST_GENERIC`
7281

7382
There are also guest config options which are dependant on the platform on which
7483
Firecracker is run:
@@ -142,6 +151,65 @@ following configurations:
142151
- Only legacy mechanisms
143152
- Both ACPI and legacy mechanisms
144153

154+
##### Booting with PCI:
155+
156+
Firecracker supports booting guest microVMs with PCI support. This option is enabled
157+
using the `--enable-pci` flag when launching the Firecracker process. With PCI enabled,
158+
Firecracker will create all VirtIO devices using a PCI VirtIO transport. The PCI transport
159+
typically achieves higher throughput and lower latency for VirtIO devices. No further, per
160+
device, configuration is needed to enable the PCI transport.
161+
162+
PCI support is optional; if it is not enabled Firecracker will create VirtIO devices using
163+
the MMIO transport.
164+
165+
For Firecracker microVMs to boot properly with PCI support, use a guest kernel built with
166+
PCI support. The relevant Kconfig flags are:
167+
168+
```
169+
CONFIG_BLK_MQ_PCI=y
170+
CONFIG_PCI=y
171+
CONFIG_PCI_MMCONFIG=y
172+
CONFIG_PCI_MSI=y
173+
CONFIG_PCIEPORTBUS=y
174+
CONFIG_VIRTIO_PCI=y
175+
CONFIG_PCI_HOST_COMMON=y
176+
CONFIG_PCI_HOST_GENERIC=y
177+
```
178+
179+
Moreover, make sure that the kernel command line **does NOT** include the `pci=off` slug,
180+
which disables PCI support during boot time within the guest. When PCI is disabled,
181+
Firecracker will add this slug in the command line to instruct the guest kernel to skip
182+
useless PCI checks. For more info, look into the section for
183+
[Kernel command line parameters](#kernel-command-line-parameters)
184+
185+
> [!NOTE]
186+
>
187+
> `CONFIG_PCI` Kconfig option is needed even when booting microVMs without PCI
188+
> support in case users want to use ACPI to boot. See [here](#booting-with-acpi-x86_64-only)
189+
> for more info.
190+
191+
## Kernel command line parameters
192+
193+
By default, Firecracker will boot a guest microVM passing the following command line
194+
parameters to the kernel:
195+
196+
`reboot=k panic=1 nomodule 8250.nr_uarts=0 i8042.noaux i8042.nomux i8042.dumbkbd swiotlb=noforce`.
197+
198+
- `reboot=k` shut down the guest on reboot, instead of well... rebooting
199+
- `panic=1` on panic, reboot after 1 second
200+
- `nomodule` disable loadable kernel module support
201+
- `8250.nr_uarts=0` disable 8250 serial interface
202+
- `i8042.noaux` do not probe the i8042 controller for an attached mouse (save boot time)
203+
- `i8042.nomux` do not probe i8042 for a multiplexing controller (save boot time)
204+
- `i8042.dumbkbd` do not attempt to control kbd state via the i8042 (save boot time)
205+
- `swiotlb=noforce` disable software bounce buffers (SWIOTLB)
206+
207+
When running without [PCI support](#booting-with-pci), Firecracker will also append `pci=off` to
208+
the above list. This option instructs the guest kernel to avoid PCI probing.
209+
210+
Users can provide their own command line parameters through the `boot_args` field of the `/boot-source`
211+
[Firecracker API](../src/firecracker/swagger/firecracker.yaml).
212+
145213
## Caveats
146214

147215
- [Snapshot compatibility across kernel versions](snapshotting/snapshot-support.md#snapshot-compatibility-across-kernel-versions)

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /