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 0273479

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 4ee4c68 commit 0273479

File tree

4 files changed

+82
-3
lines changed

4 files changed

+82
-3
lines changed

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,12 @@ 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 the
61+
MMIO transport instead.
5662

5763
### Changed
5864

‎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: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -194,9 +194,16 @@ 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
201+
a PCI VirtIO transport. This flag is optional. If not passed, Firecracker will
202+
create devices using the legacy MMIO transport. We suggest that users enable the
203+
PCI transport, as it yields higher throughput and lower latency for VirtIO
204+
devices. For more information regarding guest kernel requirements for using PCI
205+
look at our [kernel policy documentation](./kernel-policy.md).
206+
200207
In a new terminal (do not close the 1st one):
201208

202209
```bash
@@ -240,7 +247,7 @@ sudo curl -X PUT --unix-socket "${API_SOCKET}" \
240247
"http://localhost/logger"
241248

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

245252
ARCH=$(uname -m)
246253

‎docs/kernel-policy.md‎

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

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

0 commit comments

Comments
(0)

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