@@ -13,6 +13,9 @@ First, change to the `uefi-test-runner` directory:
1313cd ' uefi-test-runner'
1414```
1515
16+ Please take a quick look at the README for an overview of the system requirements
17+ of the test runner.
18+ 1619Make some changes in your favourite editor / IDE:
1720I use [ VS Code] [ code ] with the [ RLS] [ rls ] extension.
1821
@@ -24,11 +27,50 @@ Test your changes:
2427
2528The line above will open a QEMU window where the test harness will run some tests.
2629
30+ Any contributions are also expected to pass [ Clippy] [ clippy ] 's static analysis,
31+ which you can run as follows:
32+ 33+ ``` shell
34+ ./build.py clippy
35+ ```
36+ 37+ [ clippy ] : https://github.com/rust-lang-nursery/rust-clippy
2738[ code ] : https://code.visualstudio.com/
2839[ rls ] : https://github.com/rust-lang-nursery/rls-vscode
2940
3041## Style guide
3142
3243This repository follows Rust's [ standard style] [ style ] , the same one imposed by ` rustfmt ` .
3344
45+ You can apply the standard style to the whole package by running ` cargo fmt --all ` .
46+ 3447[ style ] : https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md
48+ 49+ ## UEFI pitfalls
50+ 51+ Interfacing with a foreign and unsafe API is a difficult exercise in general, and
52+ UEFI is certainly no exception. This section lists some common pain points that
53+ you should keep in mind while working on UEFI interfaces.
54+ 55+ ### Enums
56+ 57+ Rust and C enums differ in many way. One safety-critical difference is that the
58+ Rust compiler assumes that all variants of Rust enums are known at compile-time.
59+ UEFI, on the other hand, features many C enums which can be freely extended by
60+ implementations or future versions of the spec.
61+ 62+ These enums must not be interfaced as Rust enums, as that could lead to undefined
63+ behavior. Instead, integer newtypes with associated constants should be used. The
64+ ` newtype_enum ` macro is provided by this crate to ease this exercise.
65+ 66+ ### Pointers
67+ 68+ Pointer parameters in UEFI APIs come with many safety conditions. Some of these
69+ are usually expected by unsafe Rust code, while others are more specific to the
70+ low-level environment that UEFI operates in:
71+ 72+ - Pointers must reference physical memory (no memory-mapped hardware)
73+ - Pointers must be properly aligned for their target type
74+ - Pointers may only be NULL where UEFI explicitly allows for it
75+ - When an UEFI function fails, nothing can be assumed about the state of data
76+ behind ` *mut ` pointers.
0 commit comments