Document os_prefix, overlay_prefix, upstream_kernel #1433
Conversation
|
LGTM. @lurch ? |
|
Ping @lurch. |
|
|
||
| `os_prefix` is an optional setting that allows you to choose between multiple versions of the kernel and Device Tree files installed on the same card. Any value in `os_prefix` is prepended to (stuck in front of) the name of any operating system files loaded by the firmware, where "operating system files" is defined to mean kernels, initramfs, cmdline.txt, .dtbs and overlays. The prefix would commonly be a directory name, but it could also be part of the filename such as "test-". For this reason, directory prefixes must include the trailing `/` character. | ||
|
|
||
| In an attempt to reduce the chance of a non-bootable system, the firmware first tests the supplied prefix value for viability - unless the expected kernel and .dtb can be found at the new location/name, the prefix is ignored (set to ""). A special case of this viability test is applied to overlays, which will only be loaded from `${os_prefix}${overlay_prefix}` (where the default value of [`overlay_prefix`](#overlay_prefix) is "overlays/") if `${os_prefix}${overlay_prefix}README` exists, otherwise it ignores `os_prefix` and treats overlays as shared. |
There was a problem hiding this comment.
I wonder if it's worth somehow cross-linking this to https://github.com/raspberrypi/documentation/blob/master/configuration/config-txt/boot.md where the "expected kernel names" are described?
On a side-note, should https://github.com/raspberrypi/documentation/blob/master/configuration/boot_folder.md say something about kernel filenames?? @JamesH65
There was a problem hiding this comment.
On a side-note, should https://github.com/raspberrypi/documentation/blob/master/configuration/boot_folder.md say something about kernel filenames?? @JamesH65
Yes, I'll do that today.
They are AIUI:
kernel.img -> Up to BCM2836? (Pi0, PI1, Pi2 with 2836)
kernel7.img -> 2837 (Pi2 with 2837, Pi3)
kernel7l.img -> 2711 (Pi4), standard 32bit kernel with LPAE
kernel8.img -> Beta 64bit kernel
There was a problem hiding this comment.
There was a problem hiding this comment.
Bit confused about kernel.img and its use. Not sure that linked page is correct (IIRC, I wrote it...)
There was a problem hiding this comment.
I'll leave cross-linking to the experts.
There was a problem hiding this comment.
@JamesH65 Do you think it's worth making the "expected kernel and .dtb" text in the bit above a link to https://github.com/raspberrypi/documentation/blob/master/configuration/boot_folder.md ❔
|
|
||
| To allow a common DTB to be used, if the upstream file isn't found the firmware will load the downstream variant instead and automatically apply the "upstream" overlay. | ||
| The firmware will also prefer upstream Linux names for DTBs (`bcm2837-rpi-3-b.dtb` instead of `bcm2710-rpi-3-b.dtb`, for example). If the upstream file isn't found the firmware will load the downstream variant instead and automatically apply the "upstream" overlay to make some adjustments. Note that this process happens _after_ the `os_prefix` has been finalised. |
There was a problem hiding this comment.
Does the "upstream overlay" have a specific filename that could be mentioned here, or is it more complex than that?
There was a problem hiding this comment.
Don't confuse the name of the overlay with the name of the file.
There was a problem hiding this comment.
That's kinda what I was getting at - perhaps it should say:
and automatically apply the "upstream" overlay (upstream.dtbo) to make some adjustments.
?
There was a problem hiding this comment.
I don't see the point of emphasising the filename - overlays are referred to by name, not by filename. The overlay filename convention has changed before, but the names of the overlays didn't have to.
There was a problem hiding this comment.
Fair enough - as somebody unfamiliar with DeviceTree, I had no clue what apply the "upstream" overlay was inferring. But I guess others are probably less clueless than me 😁
|
@pelwell This is a bit of a side-question, but with the talk in here about |
Don't think it would do any harm, but not entirely convinced it's necessary, although did just put in that rather splendid table... |
|
Assuming you quoted the wrong comment in your reply James? Yeah, I waited for your splendid table to get merged before making the link-suggestion on this PR 😉 |
|
|
|
Are these comments going to converge anytime soon? |
|
I'm inclined to merge now and fix any other problems later. |
|
No complaints so merging. |
Some much needed documentation for the newer loader features.