uefi: update open protocol doc

[phip1611]

I have been trying to get non-exclusive access to a protocol as an app, but I don't understand the API yet

Use boot::open_protocol with OpenProtocolAttributes::GetProtocol. Here's an example:

uefi-rs/uefi-test-runner/src/proto/media.rs

Lines 257 to 264 in d30f3c3

	let block_io = boot::open_protocol::<BlockIO>(
	OpenProtocolParams {
	handle,
	agent: boot::image_handle(),
	controller: None,
	},
	OpenProtocolAttributes::GetProtocol,
	)

The documentation (and spec) are a little confusing since they say it's for drivers, but it works just as well with applications. (You can see in edk2 that BY_HANDLE_PROTOCOL and GET_PROTOCOL are handled the same way, and you can see example usages in popular UEFI applications such as shim and grub.) We should certainly update our docs to make this less confusing.

Originally posted by @nicholasbishop in #1725

[crawfxrd]

I had some trouble with this as well when porting code that used HandleProtocol (used everywhere in edk2), and originally ended up going through uefi-raw instead to use handle_protocol to keep it 1:1.

So IMO it would be nice to have:

• uefi
  • The code example using GetProtocol should be included in the docs
  • With a note that this is the replacement for handle_protocol
  • If possible, searching for handle_protocol should show open_protocol as a result
• uefi-raw
  • handle_protocol should add a note/warning to use open_protocol instead

[seijikun]

I use shared / non-exclusive access to protocols for basically everything I do, because I use a lot of protocols in application context that are more meant to be used by drivers to produce other services.
If you open these exclusive, everything bursts into flames and cute kitties are dying somewhere.
I use this helper throughout my entire app:

pub fn get_open_protocol<P: ProtocolPointer + ?Sized>(handle: Handle) -> Result<ScopedProtocol<P>> {
	let open_opts = OpenProtocolParams {
		handle,
		agent: image_handle(),
		controller: None,
	};
	let open_attrs = OpenProtocolAttributes::GetProtocol;
	unsafe { uefi::boot::open_protocol(open_opts, open_attrs) }
}

// usage
let proto = get_open_protocol::<PciRootBridgeIo>(pci_handle);

Maybe it would make sense to add a convenience method like open_protocol_exclusive() for this?

[crawfxrd]

Also potentially something for LocateProtocol, since that got removed as well. I used that in combination with ReinstallProtocolInterface to replace edk2 interfaces with my own. Now it's get_handle_for_protocol() + open_protocol().

[phip1611]

not sure if we have anything to do here @nicholasbishop ? Can we rephrase the issue to be more specfici? or should we close it?