Safety requirement documentation of `FrameBuffer::as_mut_ptr` and GOP guarantees

[mbrla0]

The current documentation for uefi::proto::console::gop::FrameBuffer::as_mut_ptr states:

To use this pointer safely and correctly, you must…
[...]

• Make sure that the pointer does not outlive the FrameBuffer

On some implementations this framebuffer pointer can be used after exiting boot services, but that is not guaranteed by the UEFI Specification.

I believe the safety requirement may be misleading, and the point being made about the UEFI Specification is incorrect.

For the safety requirement, I believe the documentation does not make it clear whether "FrameBuffer" means the instance of the FrameBuffer struct the pointer was taken from, or the UEFI framebuffer itself. If the former interpretation is true, then the assertion that "On some implementations this framebuffer pointer can be used after exiting boot services" seems to imply a scenario in which one must keep the original GraphicsOutput structure alive even after having exited boot services in order for it to be safe to use the pointer, which seems to me to not make much sense, as far as UEFI goes.

And as for the lack of guarantees in the specification, while I realize that the spec is rather obtuse, it does seem to give a tacit guarantee that direct framebuffer access is allowed even after exiting boot services:

Graphics output is important in the pre-boot space to support modern firmware features. These features include the display of logos, the localization of output to any language, and setup and configuration screens.

Graphics output may also be required as part of the startup of an operating system. There are potentially times in modern operating systems prior to the loading of a high performance OS graphics driver where access to graphics output device is required. The Graphics Output Protocol supports this capability by providing the EFI OS loader access to a hardware frame buffer and enough information to allow the OS to draw directly to the graphics output device.

Note how the specification explicitly paints the protocol as being useful to providing graphics output to an operating system before high-performance graphics are loaded, and how it distinguishes the "EFI OS loader" from the operating system itself in the rest of the paragraph.

Additionally, Linux's efifb driver directly writes to the physical framebuffer address acquired in the stub loader through GOP by taking the value of frame_buffer_base, which is also the value that is ultimately returned by as_mut_ptr. While this doesn't means it's a de jure gurantee, the fact that Linux seems confident enough to do this seems to indicate that it is a de facto guarantee, at the very least.

[phip1611]

I was often thinking about this too, and the fact that Linux relies on that is a pretty good indicator. I just never found anything specific (a spec or so) to rely on ... thanks for bringing this up!

[nicholasbishop]

For reference, here's some previous discussion on using the framebuffer after exiting boot services: #613 (comment)

and the fact that Linux relies on that is a pretty good indicator.

I think this is stated a little too strongly. Linux doesn't rely on efifb nor make any guarantees about efifb working after exiting boot services (as far as I know). If we do testing on a broad range of machines and find it works, I wouldn't object to adding that information to our documentation. But I don't think we can guarantee it's not UB in the safety doc.

[phip1611]

I think @nicholasbishop probably has seen more UEFI systems out there in his work time than I did. Thanks for your thoughts!

So how do we proceed here? Obviously, we cannot try 40 different boards with different UEFI firmware on it. 🤔

I wonder if virtually all firmware out there is based on edk2 - or if there are other major implementations. If so, looking at the behavior of edk2 should be sufficient, right?

[mbrla0]

Linux doesn't rely on efifb nor make any guarantees about efifb working after exiting boot services (as far as I know).

efifb is a regular driver that runs after the kernel has been started. The kernel's EFI stub loader (which sets up the display through GOP for use with efifb later) exits boot services right before starting the kernel proper. And the docs for efifb state that booting through the EFI stub loader is needed for the driver to work, so I think it's reasonable to assume that the expectation here is that the driver will be running after boot services have been exited.

There's no explicit guarantee anywhere, granted, but I don't think there would be much of a point in having a driver that can only run after boot services have been exited, and which drives the display by writing to the address taken from GOP, if it wasn't expected that one could do this after exiting boot services.

Additionally, I don't think it makes much sense to argue whether or not Linux itself relies on it. efifb is an optional driver, and Linux works just fine without it, same as it would if you were to disable the driver for a device you don't have. What I think is interesting to point out, though, is that widely-used distributions ship with a kernel that has it enabled by default, including Debian and Arch. A cursory glance at the Arch Forums indicates that people are using this driver just fine¹ in the real world.

Footnotes

1. Well, mostly. That post is about an issue they were having with it, but it's in regards to lack of options for mode selection, which isn't what's at hand here. ↩

[mbrla0]

For reference, here's some previous discussion on using the framebuffer after exiting boot services: #613 (comment)

I absolutely agree that the spec is not exactly clear on this¹, and at best the guarantee it gives is implicit, and so I understand not being comfortable stating this is allowed in the documentation. But I think the wording around whether or not this is allowed by UEFI in the existing docs is a little too strong in light of the actual wording in the specification, and the fact that in practice there are Linux drivers which rely on just that.

Footnotes

1. As it isn't on many things. ↩

[nicholasbishop]

I do agree with your point about this being unclear:

I believe the documentation does not make it clear whether "FrameBuffer" means the instance of the FrameBuffer struct the pointer was taken from, or the UEFI framebuffer itself

I'm not sure yet exactly how we should phrase it, but it can definitely be improved.