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