Conversation
| //! | ||
| //! ## Mapping of C Qualifiers to Rust | ||
| //! | ||
| //! The spec annotates parameters with `IN`, `OUT`, `IN OUT`, `CONST` and |
There was a problem hiding this comment.
@nicholasbishop from everything that has happened today, I think this is the most interesting to you. My first take on a writeup and future guidance.
I know that we are not yet 100% perfect here and there are likely a few things still inconsistent or one can argue about them - I fully agree. I am nevertheless very confident that today's spec and UB fixes are a significant step forward.
| //! ## Mapping of C Qualifiers to Rust | ||
| //! | ||
| //! The spec annotates parameters with `IN`, `OUT`, `IN OUT`, `CONST` and | ||
| //! `OPTIONAL`. In C these are comments; in Rust they become pointer types, |
There was a problem hiding this comment.
I'm unclear on this part: "in Rust they become pointer types". Since our signature has to match the C code, optionals don't really affect the Rust signature except in the case of function pointers, which can't otherwise be null in Rust.
| //! | `IN T *Name`, `IN CONST T *Name` | `*const T` | | ||
| //! | `OUT T *Name`, `IN OUT T *Name` | `*mut T` | | ||
| //! | `IN T *Name OPTIONAL` | `*const T` | | ||
| //! | `OUT T *Name OPTIONAL` | `Option<NonNull<T>>` | |
There was a problem hiding this comment.
Is this last row accurate? NonNull isn't currently used in uefi-raw, which I think is probably a fine choice since we generally want to closely match the C API, which doesn't have this concept.
There was a problem hiding this comment.
I think we have it at a few places. Let me double check
| //! - `This` is `*const Self` if the function only reads the protocol | ||
| //! instance, otherwise `*mut Self`. | ||
| //! - Firmware-owned structures that consumers only read, such as `Mode` | ||
| //! pointers, are `*const` even where C has no `CONST`. |
There was a problem hiding this comment.
I disagree with this convention. Quoting from api_guidelines.md:
Pointer fields in structs should always be
*mut. Even if the pointer should
not be used for mutation by bootloaders and OSes, these types are intended to be
useful for UEFI implementations as well, which may need to mutate data.
2 participants
Let's document how we actually model things in uefi-raw.
Checklist