| 1 | |
| 2 |
|
| 3 | ==========
|
| 4 | Guidelines
|
| 5 | ==========
|
| 6 |
|
| 7 | This document describes the general project guidelines that apply to nova-core
|
| 8 | and nova-drm.
|
| 9 |
|
| 10 | Language
|
| 11 | ========
|
| 12 |
|
| 13 | The Nova project uses the Rust programming language. In this context, all rules
|
| 14 | of the Rust for Linux project as documented in
|
| 15 | :doc:`../../rust/general-information` apply. Additionally, the following rules
|
| 16 | apply.
|
| 17 |
|
| 18 | - Unless technically necessary otherwise (e.g. uAPI), any driver code is written
|
| 19 | in Rust.
|
| 20 |
|
| 21 | - Unless technically necessary, unsafe Rust code must be avoided. In case of
|
| 22 | technical necessity, unsafe code should be isolated in a separate component
|
| 23 | providing a safe API for other driver code to use.
|
| 24 |
|
| 25 | Style
|
| 26 | -----
|
| 27 |
|
| 28 | All rules of the Rust for Linux project as documented in
|
| 29 | :doc:`../../rust/coding-guidelines` apply.
|
| 30 |
|
| 31 | For a submit checklist, please also see the `Rust for Linux Submit checklist
|
| 32 | addendum <https://rust-for-linux.com/contributing#submit-checklist-addendum>`_.
|
| 33 |
|
| 34 | Documentation
|
| 35 | =============
|
| 36 |
|
| 37 | The availability of proper documentation is essential in terms of scalability,
|
| 38 | accessibility for new contributors and maintainability of a project in general,
|
| 39 | but especially for a driver running as complex hardware as Nova is targeting.
|
| 40 |
|
| 41 | Hence, adding documentation of any kind is very much encouraged by the project.
|
| 42 |
|
| 43 | Besides that, there are some minimum requirements.
|
| 44 |
|
| 45 | - Every non-private structure needs at least a brief doc comment explaining the
|
| 46 | semantical sense of the structure, as well as potential locking and lifetime
|
| 47 | requirements. It is encouraged to have the same minimum documentation for
|
| 48 | non-trivial private structures.
|
| 49 |
|
| 50 | - uAPIs must be fully documented with kernel-doc comments; additionally, the
|
| 51 | semantical behavior must be explained including potential special or corner
|
| 52 | cases.
|
| 53 |
|
| 54 | - The APIs connecting the 1st level driver (nova-core) with 2nd level drivers
|
| 55 | must be fully documented. This includes doc comments, potential locking and
|
| 56 | lifetime requirements, as well as example code if applicable.
|
| 57 |
|
| 58 | - Abbreviations must be explained when introduced; terminology must be uniquely
|
| 59 | defined.
|
| 60 |
|
| 61 | - Register addresses, layouts, shift values and masks must be defined properly;
|
| 62 | unless obvious, the semantical sense must be documented. This only applies if
|
| 63 | the author is able to obtain the corresponding information.
|
| 64 |
|
| 65 | Acceptance Criteria
|
| 66 | ===================
|
| 67 |
|
| 68 | - Patches must only be applied if reviewed by at least one other person on the
|
| 69 | mailing list; this also applies for maintainers.
|