raspberrypi · aallan · Jan 16, 2024 · Jan 16, 2024
diff --git a/documentation/asciidoc/computers/config_txt/boot.adoc b/documentation/asciidoc/computers/config_txt/boot.adoc
@@ -51,6 +51,7 @@ The `initramfs` command specifies both the ramfs filename *and* the memory addre
 
 NOTE: This option uses different syntax from all the other options, and you should not use a `=` character here.
 
+[[auto_initramfs]]
 === `auto_initramfs`
 
 If `auto_initramfs` is set to `1`, look for an initramfs file using the same rules as the kernel selection.

diff --git a/documentation/asciidoc/computers/config_txt/overclocking.adoc b/documentation/asciidoc/computers/config_txt/overclocking.adoc
@@ -2,7 +2,7 @@
 
 The kernel has a https://www.kernel.org/doc/html/latest/admin-guide/pm/cpufreq.html[CPUFreq] driver with the "powersave" governor enabled by default, switched to "ondemand" during boot, when xref:configuration.adoc#raspi-config[raspi-config] is installed. With "ondemand" governor, CPU frequency will vary with processor load. You can adjust the minimum values with the `*_min` config options or disable dynamic clocking by applying a static scaling governor ("powersave" or "performance") or with `force_turbo=1`.
 
-Overclocking and overvoltage will be disabled at runtime when the SoC reaches `temp_limit` (see below), which defaults to 85°C, in order to cool down the SoC. You should not hit this limit with Raspberry Pi 1 and Raspberry Pi 2, but you are more likely to with Raspberry Pi 3 and newer Overclocking and overvoltage are also disabled when an undervoltage situation is detected.
+Overclocking and overvoltage will be disabled at runtime when the SoC reaches `temp_limit` (see below), which defaults to 85°C, in order to cool down the SoC. You should not hit this limit with Raspberry Pi 1 and Raspberry Pi 2, but you are more likely to with Raspberry Pi 3 and newer. Overclocking and overvoltage are also disabled when an undervoltage situation is detected.
 
 NOTE: For more information xref:raspberry-pi.adoc#frequency-management-and-thermal-control[see the section on frequency management and thermal control].
 

diff --git a/documentation/asciidoc/computers/config_txt/pi4-hdmi.adoc b/documentation/asciidoc/computers/config_txt/pi4-hdmi.adoc
@@ -4,7 +4,7 @@ In order to support dual displays, and modes up to 4k60, the Raspberry Pi 4 has
 
 Every HDMI mode has a list of timings that control all the parameters around sync pulse durations. These are typically defined via a pixel clock, and then a number of active pixels, a front porch, sync pulse, and back porch for each of the horizontal and vertical directions.
 
-Running everything at 2 pixels per clock means that the Raspberry Pi 4 cannot support a timing where _any_ of the horizontal timings are not divisible by 2. The firmware and Linux kernel will filter out any mode that does not fulfill this criteria.
+Running everything at 2 pixels per clock means that the Raspberry Pi 4 cannot support a timing where _any_ of the horizontal timings are not divisible by 2. The firmware and Linux kernel will filter out any mode that does not fulfil this criteria.
 
 There is only one mode in the CEA and DMT standards that falls into this category - DMT mode 81, which is 1366x768 @ 60Hz. This mode has odd values for the horizontal sync and back porch timings. It's also an unusual mode for having a width that isn't divisible by 8.
 

diff --git a/documentation/asciidoc/computers/configuration/boot_folder.adoc b/documentation/asciidoc/computers/configuration/boot_folder.adoc
@@ -1,91 +1,103 @@
-== The `boot` Folder
+== The boot folder
 
-In a basic xref:os.adoc[Raspberry Pi OS] install, the boot files are stored on the first partition of the SD card, which is formatted with the FAT file system. This means that it can be read on Windows, macOS, and Linux devices.
+Raspberry Pi OS stores boot files on the first partition of the SD card, formatted with the FAT file system.
 
-When the Raspberry Pi is powered on, it loads various files from the boot partition/folder in order to start up the various processors, then it boots the Linux kernel.
+On startup, each Raspberry Pi loads various files from the boot partition in order to start up the various processors before the Linux kernel boots.
 
-Once Linux has booted, the boot partition is mounted as `/boot/firmware/`.
+On boot, Linux mounts the boot partition as `/boot/firmware/`.
 
 NOTE: Prior to _Bookworm_, Raspberry Pi OS stored the boot partition at `/boot/`. Since _Bookworm_, the boot partition is located at `/boot/firmware/`.
 
-=== Boot Folder Contents
+=== `bootcode.bin`
 
-==== bootcode.bin
+The bootloader, loaded by the SoC on boot. It performs some very basic setup, and then loads one of the `start*.elf` files.
 
-This is the bootloader, which is loaded by the SoC on boot; it does some very basic setup, and then loads one of the `start*.elf` files. `bootcode.bin` is not used on the Raspberry Pi 4 or Raspberry Pi 5, because it has been replaced by boot code in the xref:raspberry-pi.adoc#raspberry-pi-boot-eeprom[onboard EEPROM].
+The Raspberry Pi 4 and 5 do not use `bootcode.bin`. It has been replaced by boot code in the xref:raspberry-pi.adoc#raspberry-pi-boot-eeprom[onboard EEPROM].
 
-==== start.elf, start_x.elf, start_db.elf, start_cd.elf, start4.elf, start4x.elf, start4db.elf, start4cd.elf
+=== `start*.elf`
 
-These are binary blobs (firmware) that are loaded on to the VideoCore GPU in the SoC, which then take over the boot process.
-`start.elf` is the basic firmware, `start_x.elf` also includes additional codecs, `start_db.elf` can be used for debugging purposes and `start_cd.elf` is a cut-down version of the firmware. `start_cd.elf` removes support for hardware blocks such as codecs and 3D as well as having initial framebuffer limitations. The cut-down firmware is automatically used when `gpu_mem=16` is specified in `config.txt`.
+Binary firmware blobs loaded onto the VideoCore GPU in the SoC, which then take over the boot process.
+
+* `start.elf` is the basic firmware.
+* `start_x.elf` includes additional codecs.
+* `start_db.elf` can be used for debugging purposes.
+* `start_cd.elf` is a cut-down version of the firmware that removes support for hardware blocks such as codecs and 3D; it also imposes initial framebuffer limitations. The cut-down firmware is automatically used when `gpu_mem=16` is specified in `config.txt`.
 
 `start4.elf`, `start4x.elf`, `start4db.elf` and `start4cd.elf` are equivalent firmware files specific to the Raspberry Pi 4-series (Model 4B, Pi 400, Compute Module 4 and Compute Module 4S).
 
-More information on how to use these files can be found in xref:config_txt.adoc#boot-options[the `config.txt` section].
+For more information on how to use these files, see the xref:config_txt.adoc#boot-options[`config.txt` documentation].
+
+The Raspberry Pi 5 does not use `elf` files. The firmware is self-contained within the bootloader EEPROM.
+
+=== `fixup*.dat`
+
+Linker files found in matched pairs with the `start*.elf` files listed in the previous section.
+
+=== `cmdline.txt`
 
-The Raspberry Pi 5 firmware is self-contained withing the bootloader EEPROM and does not load firmware `.elf` files from the boot filesystem.
+The kernel <<the-kernel-command-line,command line>> passed into the kernel at boot.
 
-==== fixup*.dat
+=== `config.txt`
 
-These are linker files and are matched pairs with the `start*.elf` files listed in the previous section.
+Contains many configuration parameters for setting up the Raspberry Pi. For more information, see the xref:config_txt.adoc[`config.txt` documentation].
 
-==== cmdline.txt
+NOTE: Raspberry Pi 5 requires a non-empty `config.txt` file in the boot partition.
 
-The kernel <<the-kernel-command-line,command line>> passed in to the kernel when it boots.
+=== `issue.txt`
 
-==== config.txt
+Text-based housekeeping information containing the date and git commit ID of the distribution.
 
-Contains many configuration parameters for setting up the Raspberry Pi. See xref:config_txt.adoc[the `config.txt` section].
+=== `initramfs*`
 
-NOTE: Raspberry Pi 5 requires that the boot partition contains a non-empty `config.txt` file.
+Contents of the initial ramdisk. This loads a temporary root file system into memory before the real root file system can be mounted.
 
-==== issue.txt
+NOTE: Since Bookworm, Raspberry Pi OS includes an `initramfs` file by default. To enable the initial ramdisk, configure it in xref:config_txt.adoc[`config.txt`] with the xref:config_txt.adoc#auto_initramfs[`auto_initramfs`] keyword.
 
-Some text-based housekeeping information containing the date and git commit ID of the distribution.
+=== `ssh` or `ssh.txt`
 
-==== ssh or ssh.txt
+When this file is present, enables SSH at boot. SSH is otherwise disabled by default.
 
-When this file is present, SSH will be enabled on boot. The contents don't matter, it can be empty. SSH is otherwise disabled by default.
+NOTE: The contents do not matter. Even an empty file enables SSH.
 
-==== Device Tree files
+=== Device Tree blob files (`*.dtb`)
 
-There are various Device Tree blob files, which have the extension `.dtb`. These contain the hardware definitions of the various models of Raspberry Pi, and are used on boot to set up the kernel xref:configuration.adoc#part3.1[according to which Raspberry Pi model is detected].
+Device tree blob files contain the hardware definitions of the various models of Raspberry Pi. These files set up the kernel at boot xref:configuration.adoc#part3.1[based on the detected Raspberry Pi model].
 
-==== Kernel Files
+=== Kernel files (`*.img`)
 
-The boot folder will contain various xref:linux_kernel.adoc#kernel[kernel] image files, used for the different Raspberry Pi models:
+Various xref:linux_kernel.adoc#kernel[kernel] image files that correspond to Raspberry Pi models:
 
 |===
 | Filename | Processor | Raspberry Pi model | Notes
 
-| kernel.img
+| `kernel.img`
 | BCM2835
 | Pi Zero, Pi 1
 |
 
-| kernel7.img
+| `kernel7.img`
 | BCM2836, BCM2837
 | Pi Zero 2 W, Pi 2, Pi 3
 | Later Pi 2 uses the BCM2837
 
-| kernel7l.img
+| `kernel7l.img`
 | BCM2711
 | Pi 4, Pi 400, CM4, CM4-S
 | Large Physical Address Extension (LPAE)
 
-| kernel8.img
+| `kernel8.img`
 | BCM2837, BCM2711, BCM2712
 | Pi Zero 2 W, Pi 2, Pi 3, Pi 4, Pi 400, CM4, CM4-S, Pi 5
 | xref:config_txt.adoc#boot-options[64-bit kernel]. Raspberry Pi 2 with BCM2836 does not support 64-bit kernels.
 
-| kernel_2712.img
+| `kernel_2712.img`
 | BCM2712
 | Pi 5
-| Pi 5 optmized xref:config_txt.adoc#boot-options[64-bit kernel].
+| Pi 5-optimized xref:config_txt.adoc#boot-options[64-bit kernel].
 |===
 
-NOTE: The architecture reported by `lscpu` is `armv7l` for systems running a 32-bit kernel (i.e. everything except `kernel8.img`), and `aarch64` for systems running a 64-bit kernel. The `l` in the `armv7l` case refers to the architecture being little-endian, not `LPAE` as is indicated by the `l` in the `kernel7l.img` filename.
+NOTE: `lscpu` reports a CPU architecture of `armv7l` for systems running a 32-bit kernel, and `aarch64` for systems running a 64-bit kernel. The `l` in the `armv7l` case refers to little-endian CPU architecture, not `LPAE` as is indicated by the `l` in the `kernel7l.img` filename.
 
-=== The Overlays Folder
+=== `overlays` folder
 
-The `overlays` sub-folder contains Device Tree overlays. These are used to configure various hardware devices that may be attached to the system, for example the Raspberry Pi Touch Display or third-party sound boards. These overlays are selected using entries in `config.txt` -- see xref:configuration.adoc#part2['Device Trees, overlays and parameters, part 2' for more info].
+Contains Device Tree overlays. These are used to configure various hardware devices, such as third-party sound boards. Entries in `config.txt` select these overlays. For more information, see xref:configuration.adoc#part2[Device Trees, overlays and parameters].
diff --git a/documentation/asciidoc/computers/raspberry-pi/bcm2711-bootloader.adoc b/documentation/asciidoc/computers/raspberry-pi/bcm2711-bootloader.adoc
@@ -558,7 +558,7 @@ Raspberry Pi 5 requires a `config.txt` file to be present to indicate that the p
 
 [[boot_ramdisk]]
 ==== boot_ramdisk
-If this property is set to `1` then the bootloader will attempt load a ramdisk file called `boot.img` containing the boot xref:configuration.adoc#boot-folder-contents[boot file-system]. Subsequent files (e.g. `start4.elf`) are read from the ramdisk instead of the original boot file-system.
+If this property is set to `1` then the bootloader will attempt load a ramdisk file called `boot.img` containing the xref:configuration.adoc#the-boot-folder[boot filesystem]. Subsequent files (e.g. `start4.elf`) are read from the ramdisk instead of the original boot file-system.
 
 The primary purpose of `boot_ramdisk` is to support `secure-boot`, however, unsigned `boot.img` files can also be useful to Network Boot or `RPIBOOT` configurations.