Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Note which settings pertain only to the bootloader... #3038

Merged
merged 8 commits into from
Aug 17, 2023
Merged

Note which settings pertain only to the bootloader... #3038

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
848a1c9
Add notes to settings applied by the bootloader
srcshelton Aug 1, 2023
1f914e6
Add notes on bootloader options to boot.adoc
srcshelton Aug 1, 2023
3a5f980
Add notes on bootloader options to overclocking.adoc
srcshelton Aug 1, 2023
3643882
Add notes on bootloader options to memory.adoc
srcshelton Aug 1, 2023
fea6b23
Fix copy/paste error in boot.adoc
srcshelton Aug 3, 2023
c0055ff
Update what_is_config_txt.adoc
srcshelton Aug 3, 2023
a8db339
Merge branch 'raspberrypi:develop' into note-bootloader-settings
srcshelton Aug 16, 2023
d6900bb
Remove standalone NOTEs...
srcshelton Aug 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions documentation/asciidoc/computers/config_txt/boot.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ These options specify the firmware files transferred to the VideoCore GPU prior

NOTE: Cut-down firmware (`start*cd.elf` and `fixup*cd.dat`) cannot be selected this way - the system will fail to boot. The only way to enable the cut-down firmware is to specify `gpu_mem=16`. The cut-down firmware removes support for cameras, codecs and 3D as well as limiting the initial early-boot framebuffer to 1080p @ 16bpp - although KMS can replace this with up-to 32bpp 4K framebuffer(s) at a later stage as with any firmware.

NOTE: `start_file` and `fixup_file` are used by the bootloader, and so are only valid in `config.txt`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Without any other context, I think these standalone NOTEs saying "only valid in config.txt" would be too confusing, given that they all appear on https://www.raspberrypi.com/documentation/computers/config_txt.html which is titled "The config.txt file".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess a link could be added to the section discussing includes - or does it just need to be made more specific by changing the end of the line to something along the lines of "… and so are not allowed in any additional included configuration file"?

The aim here is to avoid the confusion of including a file with these settings in, and then finding that they've not taken effect! 😅

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it likely that anybody who's using config.txt includes will have read the section about config.txt include files, and so will have seen the list of settings that don't work in an included file? I'm reluctant to "pollute" the rest of the config.txt documentation with (potentially confusing) information that's only of benefit to a small proportion of users.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The page is called "config.txt" makes no sense to add notes like this, adds confusion.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

d6900bb removes the individual NOTEs.


=== `start_x`, `start_debug`

These provide a shortcut to some alternative `start_file` and `fixup_file` settings, and are the recommended methods for selecting firmware configurations.
Expand All @@ -29,6 +31,8 @@ On the Raspberry Pi 4, if the files `start4x.elf` and `fixup4x.dat` are present,

`start_x=1` should be specified when using the camera module. Enabling the camera via `raspi-config` will set this automatically.

NOTE: `start_x` and `start_debug` are used by the bootloader, and so are only valid in `config.txt`

=== `disable_commandline_tags`

Set the `disable_commandline_tags` command to `1` to stop `start.elf` from filling in ATAGS (memory from `0x100`) before launching the kernel.
Expand Down Expand Up @@ -109,6 +113,8 @@ The `bootcode_delay` command delays for a given number of seconds in `bootcode.b

This is particularly useful to insert a delay before reading the EDID of the monitor, for example if the Raspberry Pi and monitor are powered from the same source, but the monitor takes longer to start up than the Raspberry Pi. Try setting this value if the display detection is wrong on initial boot, but is correct if you soft-reboot the Raspberry Pi without removing power from the monitor.

NOTE: `bootcode_delay` is used by the bootloader, and so is only valid in `config.txt`

=== `boot_delay`

The `boot_delay` command instructs to wait for a given number of seconds in `start.elf` before loading the kernel: the default value is `1`. The total delay in milliseconds is calculated as `(1000 x boot_delay) + boot_delay_ms`. This can be useful if your SD card needs a while to get ready before Linux is able to boot from it.
Expand Down Expand Up @@ -180,6 +186,8 @@ Setting `uart_2ndstage=1` causes the second-stage loader (`bootcode.bin` on devi

Be aware that output is likely to interfere with Bluetooth operation unless it is disabled (`dtoverlay=disable-bt`) or switched to the other UART (`dtoverlay=miniuart-bt`), and if the UART is accessed simultaneously to output from Linux then data loss can occur leading to corrupted output. This feature should only be required when trying to diagnose an early boot loading problem.

NOTE: `uart_2ndstage` is used by the bootloader, and so is only valid in `config.txt`

[[upstream_kernel]]
=== `upstream_kernel`

Expand Down
2 changes: 2 additions & 0 deletions documentation/asciidoc/computers/config_txt/memory.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ total_mem=1024

This value will be clamped between a minimum of 128MB, and a maximum of the total memory installed on the board.

NOTE: `gpu_mem`, `gpu_mem_256`, `gpu_mem_512`, `gpu_mem_1024` and `total_mem` are used by the bootloader, and so are only valid in `config.txt`

=== `disable_l2cache`

Setting this to `1` disables the CPU's access to the GPU's L2 cache and requires a corresponding L2 disabled kernel. Default value on BCM2835 is `0`. On BCM2836, BCM2837, and BCM2711, the ARMs have their own L2 cache and therefore the default is `1`. The standard Raspberry Pi `kernel.img` and `kernel7.img` builds reflect this difference in cache setting.
2 changes: 2 additions & 0 deletions documentation/asciidoc/computers/config_txt/overclocking.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,8 @@ WARNING: Setting any overclocking parameters to values other than those used by
| *3A+/3B+ only*. CPU speed throttle control. This sets the temperature at which the CPU clock speed throttling system activates. At this temperature, the clock speed is reduced from 1400MHz to 1200MHz. Defaults to `60`, can be raised to a maximum of `70`, but this may cause instability.
|===

NOTE: `sdram_freq` is used by the bootloader, and so is only valid in `config.txt`

This table gives the default values for the options on various Raspberry Pi models, all frequencies are stated in MHz.

[cols=",^,^,^,^,^,^,^,^,^"]
Expand Down
16 changes: 15 additions & 1 deletion documentation/asciidoc/computers/config_txt/what_is_config_txt.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,21 @@ Causes the content of the specified file to be inserted into the current file.

For example, adding the line `include extraconfig.txt` to `config.txt` will include the content of `extraconfig.txt` file in the `config.txt` file.

*Include directives are not supported by bootcode.bin or the EEPROM bootloader*
[NOTE]
====

*Include directives are not supported by the bootcode.bin or EEPROM bootloaders*.

Settings which are handled by the bootloader and so which will only take effect if they are specified in `config.txt` (rather than any additional included file) are:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be happy to keep this bit where you document which settings don't work when used in an included file, as I suspect only a very small proportion of users actually use config.txt includes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a small note block about include files is okay. NOTES per individual items, not so much.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a small note block about include files is okay. NOTES per individual items, not so much.

d6900bb removes the individual NOTEs.


* `bootcode_delay`,
* `gpu_mem`, `gpu_mem_256`, `gpu_mem_512`, `gpu_mem_1024`,
* `total_mem`,
* `sdram_freq`,
* `start_x`, `start_debug`, `start_file`, `fixup_file`,
* `uart_2ndstage`.

====

==== Conditional Filtering

Expand Down
Loading