Edit the Raspberry Pi boot configuration

The Raspberry Pi’s boot configuration consists of a series of simple text files. Depending on the model of Pi, the boot configuration either exists entirely on the boot partition (the first FAT-formatted partition on your boot media), or has a portion based in a boot EEPROM (on the Pi 4 and 5).

The format of the boot configuration is based on the classic MS-DOS INI-format, with the following variations:

  • Section and property names are case sensitive

  • Comments start with a hash-sign (#), not a semi-colon (;)

  • Comments may only start at the beginning of a line, not trailing a property

  • Ordering of sections and properties is relevant because…

  • Duplicate names are permitted with later declarations overriding earlier ones

  • Quoted values are not permitted

  • Spaces are not permitted (or more precisely are not ignored) either side of the “=” in a key=value setting and hence, should not be used

Main configuration

The main boot configuration, which applies to all models of Pi, lives in a file called config.txt placed on the boot partition of your boot media (the first FAT-formatted partition). Typically on Ubuntu, this is mounted under the path /boot/firmware. Files on the partition can only be manipulated by the root user, hence to edit the boot configuration at run-time you would use something like:

sudo vi /boot/firmware/config.txt

Below, we’ll walk through the default boot configuration on Ubuntu Server for Raspberry Pi. This will illustrate the format, and demonstrate a typical (if minimal) configuration example:

[all]
arm_64bit=1
kernel=vmlinuz
cmdline=cmdline.txt
initramfs initrd.img followkernel

Note

The lack of an equals sign in the initramfs line is intentional, and is a quirk of the config.txt format. It only applies to this property.

We start off with the [all] section. As the name implies, this applies to all Pis, whatever model, or serial number. This first block simply defines:

arm_64bit

Informs the bootloader we want to start the ARM cores in 64-bit mode (ARMv8)

kernel

Specifies the location of the Linux kernel (here, vmlinuz on the boot partition)

cmdline

The file containing the command line to pass to the Linux kernel (the single line in cmdline.txt on the boot partition). Be aware that the command line will also include parameters determined by the bootloader itself. If you query /proc/cmdline at run-time you should typically find the content of cmdline.txt is present as a suffix

initramfs

The archive containing the initial ram-disk (the content of the initial root file-system), and where to load it in memory. Here, we tell the bootloader to place it immediately after the kernel

# Enable the audio output, I2C and SPI interfaces on the GPIO header. As these
# parameters related to the base device-tree they must appear *before* any
# other dtoverlay= specification
dtparam=audio=on
dtparam=i2c_arm=on
dtparam=spi=on

We carry on, still in the [all] section, with a series of dtparam lines. These are device-tree parameters which customize the base device-tree. In this case these enable the ALSA, I²C, and SPI interfaces.

# Enable the KMS ("full" KMS) graphics overlay, leaving GPU memory as the
# default (the kernel is in control of graphics memory with full KMS)
dtoverlay=vc4-kms-v3d
disable_fw_kms_setup=1

Next are a series of options controlling video output. The two important options are:

dtoverlay

This loads the “full” KMS device-tree overlay, leaving the Linux kernel in control of the display hardware, rather than the boot firmware

disable_fw_kms_setup

This disables the firmware’s detection of the monitor (via EDID), leaving the Linux kernel to handle detection it

# Enable the serial pins
enable_uart=1

This section simply enables the serial UART on GPIO 14 and 15. This is only included on the Ubuntu Server images because headless setups (where the serial console is useful for debugging) are rela