config.txt (Raspberry Pi)

Introduction

The Raspberry Pi boot loader uses the config.txt file to hold configuration options relevant at boot time. It is a plain text file, resident in the DOS partition of the boot SD card, alongside RISCOS.IMG etc. (for more information on other files in the DOS partition, see Software information: Raspberry Pi: Firmware)

It should not be confused with cmdline.txt (which is used to pass parameters to RISC OS at boot time).

Accessing config.txt

As stated above, config.txt is in the DOS partition of the SD card. On a standard RISC OS build using a Dual-format SD card, this can be reached by double-clicking on !Boot.Loader (i.e. shift-doubleclick on !Boot and then double-click on the file called “Loader”).

Entries required by RISC OS

The suggested contents of config.txt are as follows:

[pi4]
enable_gic=1
[all]
arm_64bit=0
fake_vsync_isr=1
framebuffer_swap=0
gpu_mem=64
init_emmc_clock=100000000
kernel=RISCOS.IMG
ramfsfile=CMOS
ramfsaddr=0x508000

Note that the list is split¹ into two parts: the “pi4” section contains options for the Pi 4 only, while the “all” section contains options applicable to all versions of Raspberry Pi (including the Pi 4). Within each section, options can appear in any order: the important thing is to make sure they are in the right section!

¹ The technique of splitting the list into multiple sections is explained in detail on the Conditional filters page of the Raspberry Pi documentation.

The entries on the list have the following meanings:

• enable_gic=1
  Enables the GIC interrupt controller. As this is in the “pi4” section, it will only be actioned on the Pi 4.

• arm_64bit=0
  Tell the bootloader to boot the kernel (i.e. RISCOS.IMG) in 32-bit mode².

• fake_vsync_isr=1
  Triggers an SMI interrupt at vertical sync (VSYNC) pulse

• framebuffer_swap=0
  Corrects a problem where red and blue colour channels are swapped on some firmware/OS combinations. If you are running RISC OS 5.30 with May 2024 (or later) firmware, you may need to set this to framebuffer_swap=1

• gpu_mem=64
  Allocates 64MB RAM to the GPU. At present, this enumerates the default setting.

• init_emmc_clock=100000000
  Sets the eMMC clock rate to 100MHz. At present, this enumerates the default setting.

• kernel=RISCOS.IMG
  Filename of the RISC OS ROM

• ramfsfile=CMOS
  Name of CMOS RAM file to be loaded

• ramfsaddr=0x508000
  Address to load the CMOS RAM. This address is 5MiB after the kernel start address (0×8000) so the RISC OS ROM cannot exceed 5MiB in size.

² There has already been one incident where the firmware tried to boot all kernels in 64-bit mode. Better safe than sorry.

Optional sound entries

If you’re having trouble getting HDMI sound to work, the following two entries may help:

• hdmi_drive=2
  Forces HDMI mode (sound enabled) instead of DVI mode (no sound).

• hdmi_force_edid_audio=1
  Send audio via HDMI, ignoring any “audio not supported” indications from the monitor.

The following two entries are useful if you want to use the 3.5mm audio output jack instead of via the HDMI cable.

• hdmi_ignore_edid_audio=1
  Force the audio to use the stereo audio jack output.

• audio_pwm_mode=2
  Improves the sound quality and reduces annoying hissing.

Optional video entries

hdmi_mode and hdmi_group

These options are used to specify the monitor’s native pixel resolution. You might need them if you are using the AnyMode utility, if your monitor does not support EDID, or if you want the Pi to run “headless” (i.e. without a monitor attached, and with all communication via VNC or similar).

For example, to specify a screen size of 1920×1080, you would use:
hdmi_group=2
hdmi_mode=82

If your monitor size is not listed above, see this documentation page for other hdmi_mode and hdmi_group values.

Increasing the screen size

The largest screen size officially supported by the Pi 1/2/3 is 1920×1200. These dimensions can be increased as follows:

• max_framebuffer_width, max_framebuffer_height
  Specifies the maximum dimensions that the internal frame buffer is allowed to be. There is a trade-off between screen size and display rate: the larger the screen, the lower the display rate.

• hdmi_pixel_freq_limit
  This command allows you to overclock the GPU above its nominal pixel frequency limit of 162MHz (Pi 1/2/3) or 300Mhz (Pi 4). For example, if you want a screen display of “2560×1440,60Hz” on a Pi 3, you would need a value of 250000000 (i.e. 250MHz).
  IMPORTANT NOTE: Recent firmware versions – including the firmware distributed with RISC OS 5.28 – won’t allow RISC OS to read this value. If you want to use this feature, you will have to lock the display to the required screen dimensions, as follows:
  • Create a custom CVT mode by using the hdmi_cvt option along with hdmi_group=2 and hdmi_mode=87. For example, a 2560×1440,60Hz setting would look something like this:
    hdmi_cvt=2560 1440 60
hdmi_group=2
hdmi_mode=87
hdmi_drive=2
hdmi_pixel_freq_limit=250000000
max_framebuffer_width=2560
max_framebuffer_height=1440
  • Specify “disable_mode_changes” in cmdline.txt.
  • Add AnyMode to !Boot.Choices.Boot.Predesk.

Other video entries

• hdmi_blanking=1
  Add this line if you want the monitor to switch to standby when the DPMS screen saver activates. Without this line, the screen will go blank, but the monitor will stay “on”.

• hdmi_enable_4kp60=1
  Allows the Pi4 to use 3840×2160,60Hz (the default is to display 4K at 30Hz). Note this will increase the power consumption – and temperature – of the Pi 4. This command will not work on earlier models of Raspberry Pi: to avoid confusion, it should be placed in the “pi4” section³ of config.txt.

• hdmi_force_hotplug=1
  Forces video output to use the HDMI connector. Use this if the Pi is having difficulties detecting your HDMI display, or if you want the Pi to run “headless” (i.e. without a monitor attached).

• disable_overscan=1
  Don’t want those black borders at the edge of the screen? Try adding disable_overscan=1 to get rid of them.

• sdtv_mode=2
  This causes the composite video output to use European (PAL) picture format rather than American (NTSC) picture format. You will only need this option if you are using the composite video connector: it has no effect on video signals sent via the HDMI connector.

³ Putting it in the “pi4” section isn’t strictly necessary (as older models of Raspberry Pi will ignore it) but it does make it clear it is for the Pi 4 only.

Miscellaneous entries

The following entries may also be useful in certain circumstances:

• boot_delay
  Number of seconds to wait before loading the kernel. Use this if your SD card needs a while to get ready.

• bootcode_delay
  Number of seconds to wait before loading start.elf. Use this if your monitor takes a long time to start up (e.g. if a low-resolution desktop appears on cold boot, but restarting the Pi gives you a 1920×1080 desktop).

External links

• RPIconfig (at elinux.org) contains further information on most of the options mentioned above, and many more besides.

• On the Raspberry Pi website, documentation is split between two pages:
  • Options still supported by the Pi 5
  • Options only available on earlier Pi models (Pi Zero, Pi 1, Pi 2, Pi 3, Pi 4)