1# API Guidelines
2
3The `uefi-raw` crate should closely match the definitions in the [UEFI
4Specification], with only some light changes to make it more friendly for use in
5Rust (e.g. casing follows Rust's conventions and modules are used to provide
6some hierarchy).
7
8This document describes the API rules in detail. Some of these rules can be
9checked with `cargo xtask check-raw`, and that check is run automatically in CI
10as well. Other rules require human verification.
11
12If you are contributing to this crate and run into any problems, such as a case
13that isn't covered by the rules, or a case where following the rules seems like
14it will lead to a bad API, don't hesitate to let us know (e.g. by filing an
15[issue]).
16
17## Naming
18
19Type names should match the corresponding spec names, but drop the `EFI_` prefix
20and change to `UpperCamelCase` to match Rust's convention. For example,
21`EFI_LOAD_FILE_PROTOCOL` becomes `LoadFileProtocol`.
22
23Struct field names and function parameter names should match the corresponding
24spec names, but change the case to `snake_case` to match Rust's convention.
25
26When defining a type that isn't part of the spec (for example, a `bitflags!`
27type that represents a collection of constants in the spec), prefix the name
28with a closely-associated type that is defined in the spec. For example, mode
29constants for a `FooBarProtocol` could be collected into a `FooBarMode` type.
30
31It's OK to introduce minor naming changes from the specification where it
32improves clarity.
33
34## Layout
35
36All types must be `repr(C)`, `repr(C, packed)`, or `repr(transparent)`.
37
38Types created with the `bitflags!` macro must set `repr(transparent)`.
39
40### Dynamically Sized Types
41
42Some types in the spec end with a variable-length array. It's possible to
43represent these as [Dynamically Sized Types], but that should be left to
44higher-level APIs. In this crate, add a zero-length array at the end of the
45struct to represent the field. For example, if a struct in the spec ends with
46`CHAR16 Name[];`, represent that in Rust with `name: [Char16; 0]`.
47
48This pattern of using a `&Header` to work with dynamically-sized data is
49rejected by the Stacked Borrows model, but allowed by Tree Borrows. See [UCG
50issue 256] for more info.
51
52## Visibility
53
54Everything must have `pub` visibility.
55
56## Constants
57
58Use associated constants where possible instead of top-level constants.
59
60Protocols must have an associated `GUID` constant, for example:
61
62```rust
63impl RngProtocol {
64    pub const GUID: Guid = guid!("3152bca5-eade-433d-862e-c01cdc291f44");
65}
66```
67
68## Pointers
69
70Use pointers (`*const`/`*mut`) instead of references (`&`/`&mut`).
71
72Function pointers must be `unsafe` and have an explicit ABI (almost always
73`efiapi`). If a function pointer field can be null it must be wrapped in
74`Option`. Most function pointer fields do not need to allow null pointers
75though, unless the spec says otherwise.
76
77### Mutability
78
79Pointer mutability (`*mut` vs `*const`) is not a UB concern the way reference
80mutability is. In general, it is not UB to `cast_mut` a const pointer and write
81through it. So picking `*mut` vs `*const` is more about semantics.
82
83Pointer fields in structs should always be `*mut`. Even if the pointer should
84not be used for mutation by bootloaders and OSes, these types are intended to be
85useful for UEFI _implementations_ as well, which may need to mutate data.
86
87In function parameters, pick between `*const` and `*mut` based on how the
88parameter is described in the spec. An `OUT` or `IN OUT` pointer must be
89`*mut`. An `IN` pointer _may_ be `*mut`, but `*const` may be more appropriate if
90the parameter is described as being source data.
91
92## Allowed top-level items
93
94The allowed top-level items are `const`, `impl`, `macro`, `struct`, and
95`type`.
96
97Rust `enum`s are not allowed; use the `bitflags!` or `newtype_enum!` macros
98instead.
99
100[UEFI Specification]: https://uefi.org/specifications
101[issue]: https://github.com/rust-osdev/uefi-rs/issues/new
102[Dynamically Sized Types]: https://doc.rust-lang.org/reference/dynamically-sized-types.html
103[UCG issue 256]: https://github.com/rust-lang/unsafe-code-guidelines/issues/256
104