crates/uefi-raw/api_guidelines.md - platform/external/rust/android-crates-io - Git at Google

 # 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
	# 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