mirror of
https://github.com/rust-osdev/uefi-rs
synced 2026-08-26 18:26:05 -04:00
103 lines
4 KiB
Markdown
103 lines
4 KiB
Markdown
# API Guidelines
|
|
|
|
The `uefi-raw` crate should closely match the definitions in the [UEFI
|
|
Specification], with only some light changes to make it more friendly for use in
|
|
Rust (e.g. casing follows Rust's conventions and modules are used to provide
|
|
some hierarchy).
|
|
|
|
This document describes the API rules in detail. Some of these rules can be
|
|
checked with `cargo xtask check-raw`, and that check is run automatically in CI
|
|
as well. Other rules require human verification.
|
|
|
|
If you are contributing to this crate and run into any problems, such as a case
|
|
that isn't covered by the rules, or a case where following the rules seems like
|
|
it will lead to a bad API, don't hesitate to let us know (e.g. by filing an
|
|
[issue]).
|
|
|
|
## Naming
|
|
|
|
Type names should match the corresponding spec names, but drop the `EFI_` prefix
|
|
and change to `UpperCamelCase` to match Rust's convention. For example,
|
|
`EFI_LOAD_FILE_PROTOCOL` becomes `LoadFileProtocol`.
|
|
|
|
Struct field names and function parameter names should match the corresponding
|
|
spec names, but change the case to `snake_case` to match Rust's convention.
|
|
|
|
When defining a type that isn't part of the spec (for example, a `bitflags!`
|
|
type that represents a collection of constants in the spec), prefix the name
|
|
with a closely-associated type that is defined in the spec. For example, mode
|
|
constants for a `FooBarProtocol` could be collected into a `FooBarMode` type.
|
|
|
|
It's OK to introduce minor naming changes from the specification where it
|
|
improves clarity.
|
|
|
|
## Layout
|
|
|
|
All types must be `repr(C)`, `repr(C, packed)`, or `repr(transparent)`.
|
|
|
|
Types created with the `bitflags!` macro must set `repr(transparent)`.
|
|
|
|
### Dynamically Sized Types
|
|
|
|
Some types in the spec end with a variable-length array. It's possible to
|
|
represent these as [Dynamically Sized Types], but that should be left to
|
|
higher-level APIs. In this crate, add a zero-length array at the end of the
|
|
struct to represent the field. For example, if a struct in the spec ends with
|
|
`CHAR16 Name[];`, represent that in Rust with `name: [Char16; 0]`.
|
|
|
|
This pattern of using a `&Header` to work with dynamically-sized data is
|
|
rejected by the Stacked Borrows model, but allowed by Tree Borrows. See [UCG
|
|
issue 256] for more info.
|
|
|
|
## Visibility
|
|
|
|
Everything must have `pub` visibility.
|
|
|
|
## Constants
|
|
|
|
Use associated constants where possible instead of top-level constants.
|
|
|
|
Protocols must have an associated `GUID` constant, for example:
|
|
|
|
```rust
|
|
impl RngProtocol {
|
|
pub const GUID: Guid = guid!("3152bca5-eade-433d-862e-c01cdc291f44");
|
|
}
|
|
```
|
|
|
|
## Pointers
|
|
|
|
Use pointers (`*const`/`*mut`) instead of references (`&`/`&mut`).
|
|
|
|
Function pointers must be `unsafe` and have an explicit ABI (almost always
|
|
`efiapi`). If a function pointer field can be null it must be wrapped in
|
|
`Option`. Most function pointer fields do not need to allow null pointers
|
|
though, unless the spec says otherwise.
|
|
|
|
### Mutability
|
|
|
|
Pointer mutability (`*mut` vs `*const`) is not a UB concern the way reference
|
|
mutability is. In general, it is not UB to `cast_mut` a const pointer and write
|
|
through it. So picking `*mut` vs `*const` is more about semantics.
|
|
|
|
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.
|
|
|
|
In function parameters, pick between `*const` and `*mut` based on how the
|
|
parameter is described in the spec. An `OUT` or `IN OUT` pointer must be
|
|
`*mut`. An `IN` pointer _may_ be `*mut`, but `*const` may be more appropriate if
|
|
the parameter is described as being source data.
|
|
|
|
## Allowed top-level items
|
|
|
|
The allowed top-level items are `const`, `impl`, `macro`, `struct`, and
|
|
`type`.
|
|
|
|
Rust `enum`s are not allowed; use the `bitflags!` or `newtype_enum!` macros
|
|
instead.
|
|
|
|
[UEFI Specification]: https://uefi.org/specifications
|
|
[issue]: https://github.com/rust-osdev/uefi-rs/issues/new
|
|
[Dynamically Sized Types]: https://doc.rust-lang.org/reference/dynamically-sized-types.html
|
|
[UCG issue 256]: https://github.com/rust-lang/unsafe-code-guidelines/issues/256
|