Add `open_protocol_opt()` helpers

[phip1611]

This originated from a discussion in #1858. I argue that uefi-rs should aim for abstractions that expose less and less low-level UEFI details to the user. One example I have in mind is open_protocol_opt() -> Result<Option<ScopedProtocol<P>>>. This helps to better differentiate between "is the protocol just not there" and an actual error.

There are many cases both internal code as well as where peope will use uefi-rs where this would be very benefitial.

This cleanly distinguishes between:

• Ok(None): the protocol is not present
• Ok(Some(_)): the protocol is present and opened successfully
• Err(_): a real error occurred

Eventually, we could deprecate the old versions even.

[nicholasbishop]

Adding a bit of context from my comment in #1858 (comment):

And I would think this is the typical pattern -- if you try to open a protocol on a handle, you generally expect the protocol to exist. And even if not (e.g. if you are testing a number of handles to see which has a protocol), you probably don't care if the protocol fails to open because it doesn't support that protocol vs some other error -- you just want to move on to the next handle.

To give some real-world data, I looked through uses of open_protocol in crdyboot via codesearch.

As far as I can see, in all cases we treat "protocol not present on this handle" as an error. In most cases this is because we start by searching for a handle by protocol GUID (e.g. with boot::get_handle_for_protocol). If we make it past that step and have a handle to pass into open_protocol, then it makes sense that "protocol not present" should never happen, i.e. it's always an error.

The only case I see that is a little different is the tpm code, which has some functions that return something like Result<Option<Protocol>, Error>. But those return Ok(None) when searching for the handle fails, not when opening the protocol returns EFI_UNSUPPORTED.

Obviously the uses in crdyboot are not going to cover all patterns used in other projects though. :) Do you have examples you can share of code where open_protocol_opt would be helpful, an in particular where the caller would treat Ok(None) differently than Err?

[phip1611]

in most cases this is because we start by searching for a handle by protocol GUID (e.g. with boot::get_handle_for_protocol). If we make it past that step and have a handle to pass into open_protocol, then it makes sense that "protocol not present" should never happen, i.e. it's always an error.

I agree! Thanks for the writeup! We can keep it as is.