sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget*/translations/zh_CN/rust/coding-guidelinesmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/zh_TW/rust/coding-guidelinesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/it_IT/rust/coding-guidelinesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ja_JP/rust/coding-guidelinesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ko_KR/rust/coding-guidelinesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/pt_BR/rust/coding-guidelinesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/sp_SP/rust/coding-guidelinesmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhD/var/lib/git/docbuild/linux/Documentation/rust/coding-guidelines.rsthKubhsection)}(hhh](htitle)}(hCoding Guidelinesh]hCoding Guidelines}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(h=This document describes how to write Rust code in the kernel.h]h=This document describes how to write Rust code in the kernel.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hStyle & formattingh]hStyle & formatting}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh)}(hXTThe code should be formatted using ``rustfmt``. In this way, a person contributing from time to time to the kernel does not need to learn and remember one more style guide. More importantly, reviewers and maintainers do not need to spend time pointing out style issues anymore, and thus less patch roundtrips may be needed to land a change.h](h#The code should be formatted using }(hhhhhNhNubhliteral)}(h ``rustfmt``h]hrustfmt}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhubhX&. In this way, a person contributing from time to time to the kernel does not need to learn and remember one more style guide. More importantly, reviewers and maintainers do not need to spend time pointing out style issues anymore, and thus less patch roundtrips may be needed to land a change.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubhnote)}(hzConventions on comments and documentation are not checked by ``rustfmt``. Thus those are still needed to be taken care of.h]h)}(hzConventions on comments and documentation are not checked by ``rustfmt``. Thus those are still needed to be taken care of.h](h=Conventions on comments and documentation are not checked by }(hj&hhhNhNubj)}(h ``rustfmt``h]hrustfmt}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj&ubh2. Thus those are still needed to be taken care of.}(hj&hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj"ubah}(h]h ]h"]h$]h&]uh1j hhhhhhhNubh)}(hThe default settings of ``rustfmt`` are used. This means the idiomatic Rust style is followed. For instance, 4 spaces are used for indentation rather than tabs.h](hThe default settings of }(hjLhhhNhNubj)}(h ``rustfmt``h]hrustfmt}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jhjLubh} are used. This means the idiomatic Rust style is followed. For instance, 4 spaces are used for indentation rather than tabs.}(hjLhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hIt is convenient to instruct editors/IDEs to format while typing, when saving or at commit time. However, if for some reason reformatting the entire kernel Rust sources is needed at some point, the following can be run::h]hIt is convenient to instruct editors/IDEs to format while typing, when saving or at commit time. However, if for some reason reformatting the entire kernel Rust sources is needed at some point, the following can be run:}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh literal_block)}(hmake LLVM=1 rustfmth]hmake LLVM=1 rustfmt}hj|sbah}(h]h ]h"]h$]h&]hhuh1jzhhhKhhhhubh)}(hrIt is also possible to check if everything is formatted (printing a diff otherwise), for instance for a CI, with::h]hqIt is also possible to check if everything is formatted (printing a diff otherwise), for instance for a CI, with:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubj{)}(hmake LLVM=1 rustfmtcheckh]hmake LLVM=1 rustfmtcheck}hjsbah}(h]h ]h"]h$]h&]hhuh1jzhhhK#hhhhubh)}(hLike ``clang-format`` for the rest of the kernel, ``rustfmt`` works on individual files, and does not require a kernel configuration. Sometimes it may even work with broken code.h](hLike }(hjhhhNhNubj)}(h``clang-format``h]h clang-format}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh for the rest of the kernel, }(hjhhhNhNubj)}(h ``rustfmt``h]hrustfmt}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhu works on individual files, and does not require a kernel configuration. Sometimes it may even work with broken code.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK%hhhhubh)}(hhh](h)}(hImportsh]hImports}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK*ubh)}(h``rustfmt``, by default, formats imports in a way that is prone to conflicts while merging and rebasing, since in some cases it condenses several items into the same line. For instance:h](j)}(h ``rustfmt``h]hrustfmt}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, by default, formats imports in a way that is prone to conflicts while merging and rebasing, since in some cases it condenses several items into the same line. For instance:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK,hjhhubj{)}(h// Do not use this style. use crate::{ example1, example2::{example3, example4, example5}, example6, example7, example8::example9, };h]h// Do not use this style. use crate::{ example1, example2::{example3, example4, example5}, example6, example7, example8::example9, };}hjsbah}(h]h ]h"]h$]h&]hhƌforcelanguagerusthighlight_args}uh1jzhhhK0hjhhubh)}(h@Instead, the kernel uses a vertical layout that looks like this:h]h@Instead, the kernel uses a vertical layout that looks like this:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK:hjhhubj{)}(huse crate::{ example1, example2::{ example3, example4, example5, // }, example6, example7, example8::example9, // };h]huse crate::{ example1, example2::{ example3, example4, example5, // }, example6, example7, example8::example9, // };}hj&sbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhK Foo { // ... }h]h/// Returns a new [`Foo`]. /// /// # Examples /// // TODO: Find a better example. /// ``` /// let foo = f(42); /// ``` // FIXME: Use fallible approach. pub fn f(x: i32) -> Foo { // ... }}hjsbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhKhjhhubh)}(hX\This applies to both public and private items. This increases consistency with public items, allows changes to visibility with less changes involved and will allow us to potentially generate the documentation for private items as well. In other words, if documentation is written for a private item, then ``///`` should still be used. For instance:h](hX1This applies to both public and private items. This increases consistency with public items, allows changes to visibility with less changes involved and will allow us to potentially generate the documentation for private items as well. In other words, if documentation is written for a private item, then }(hjhhhNhNubj)}(h``///``h]h///}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh$ should still be used. For instance:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj{)}(h//// My private function. // TODO: ... fn f() {}h]h//// My private function. // TODO: ... fn f() {}}hjsbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhKhjhhubh)}(hOne special kind of comments are the ``// SAFETY:`` comments. These must appear before every ``unsafe`` block, and they explain why the code inside the block is correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.:h](h%One special kind of comments are the }(hjhhhNhNubj)}(h``// SAFETY:``h]h // SAFETY:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh* comments. These must appear before every }(hjhhhNhNubj)}(h ``unsafe``h]hunsafe}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh block, and they explain why the code inside the block is correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj{)}(hF// SAFETY: `p` is valid by the safety requirements. unsafe { *p = 0; }h]hF// SAFETY: `p` is valid by the safety requirements. unsafe { *p = 0; }}hj)sbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhKhjhhubh)}(hX``// SAFETY:`` comments are not to be confused with the ``# Safety`` sections in code documentation. ``# Safety`` sections specify the contract that callers (for functions) or implementors (for traits) need to abide by. ``// SAFETY:`` comments show why a call (for functions) or implementation (for traits) actually respects the preconditions stated in a ``# Safety`` section or the language reference.h](j)}(h``// SAFETY:``h]h // SAFETY:}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj9ubh* comments are not to be confused with the }(hj9hhhNhNubj)}(h ``# Safety``h]h# Safety}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj9ubh! sections in code documentation. }(hj9hhhNhNubj)}(h ``# Safety``h]h# Safety}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1jhj9ubhk sections specify the contract that callers (for functions) or implementors (for traits) need to abide by. }(hj9hhhNhNubj)}(h``// SAFETY:``h]h // SAFETY:}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jhj9ubhy comments show why a call (for functions) or implementation (for traits) actually respects the preconditions stated in a }(hj9hhhNhNubj)}(h ``# Safety``h]h# Safety}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj9ubh# section or the language reference.}(hj9hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]commentsah ]h"]commentsah$]h&]uh1hhhhhhhhKvubh)}(hhh](h)}(hCode documentationh]hCode documentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hRust kernel code is not documented like C kernel code (i.e. via kernel-doc). Instead, the usual system for documenting Rust code is used: the ``rustdoc`` tool, which uses Markdown (a lightweight markup language).h](hRust kernel code is not documented like C kernel code (i.e. via kernel-doc). Instead, the usual system for documenting Rust code is used: the }(hjhhhNhNubj)}(h ``rustdoc``h]hrustdoc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh; tool, which uses Markdown (a lightweight markup language).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hWTo learn Markdown, there are many guides available out there. For instance, the one at:h]hWTo learn Markdown, there are many guides available out there. For instance, the one at:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh block_quote)}(hhttps://commonmark.org/help/ h]h)}(hhttps://commonmark.org/help/h]h reference)}(hjh]hhttps://commonmark.org/help/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(h:This is how a well-documented Rust function may look like:h]h:This is how a well-documented Rust function may look like:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj{)}(hX/// Returns the contained [`Some`] value, consuming the `self` value, /// without checking that the value is not [`None`]. /// /// # Safety /// /// Calling this method on [`None`] is *[undefined behavior]*. /// /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// /// # Examples /// /// ``` /// let x = Some("air"); /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); /// ``` pub unsafe fn unwrap_unchecked(self) -> T { match self { Some(val) => val, // SAFETY: The safety contract must be upheld by the caller. None => unsafe { hint::unreachable_unchecked() }, } }h]hX/// Returns the contained [`Some`] value, consuming the `self` value, /// without checking that the value is not [`None`]. /// /// # Safety /// /// Calling this method on [`None`] is *[undefined behavior]*. /// /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// /// # Examples /// /// ``` /// let x = Some("air"); /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); /// ``` pub unsafe fn unwrap_unchecked(self) -> T { match self { Some(val) => val, // SAFETY: The safety contract must be upheld by the caller. None => unsafe { hint::unreachable_unchecked() }, } }}hjsbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhKhjhhubh)}(h^This example showcases a few ``rustdoc`` features and some conventions followed in the kernel:h](hThis example showcases a few }(hj(hhhNhNubj)}(h ``rustdoc``h]hrustdoc}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj(ubh6 features and some conventions followed in the kernel:}(hj(hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh bullet_list)}(hhh](h list_item)}(hThe first paragraph must be a single sentence briefly describing what the documented item does. Further explanations must go in extra paragraphs. h]h)}(hThe first paragraph must be a single sentence briefly describing what the documented item does. Further explanations must go in extra paragraphs.h]hThe first paragraph must be a single sentence briefly describing what the documented item does. Further explanations must go in extra paragraphs.}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjOubah}(h]h ]h"]h$]h&]uh1jMhjJhhhhhNubjN)}(hXUnsafe functions must document their safety preconditions under a ``# Safety`` section. h]h)}(hWUnsafe functions must document their safety preconditions under a ``# Safety`` section.h](hBUnsafe functions must document their safety preconditions under a }(hjkhhhNhNubj)}(h ``# Safety``h]h# Safety}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jhjkubh section.}(hjkhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjgubah}(h]h ]h"]h$]h&]uh1jMhjJhhhhhNubjN)}(hX4While not shown here, if a function may panic, the conditions under which that happens must be described under a ``# Panics`` section. Please note that panicking should be very rare and used only with a good reason. In almost all cases, a fallible approach should be used, typically returning a ``Result``. h](h)}(hWhile not shown here, if a function may panic, the conditions under which that happens must be described under a ``# Panics`` section.h](hqWhile not shown here, if a function may panic, the conditions under which that happens must be described under a }(hjhhhNhNubj)}(h ``# Panics``h]h# Panics}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh section.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hPlease note that panicking should be very rare and used only with a good reason. In almost all cases, a fallible approach should be used, typically returning a ``Result``.h](hPlease note that panicking should be very rare and used only with a good reason. In almost all cases, a fallible approach should be used, typically returning a }(hjhhhNhNubj)}(h ``Result``h]hResult}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jMhjJhhhhhNubjN)}(hlIf providing examples of usage would help readers, they must be written in a section called ``# Examples``. h]h)}(hkIf providing examples of usage would help readers, they must be written in a section called ``# Examples``.h](h\If providing examples of usage would help readers, they must be written in a section called }(hjhhhNhNubj)}(h``# Examples``h]h # Examples}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jMhjJhhhhhNubjN)}(hyRust items (functions, types, constants...) must be linked appropriately (``rustdoc`` will create a link automatically). h]h)}(hxRust items (functions, types, constants...) must be linked appropriately (``rustdoc`` will create a link automatically).h](hJRust items (functions, types, constants...) must be linked appropriately (}(hj hhhNhNubj)}(h ``rustdoc``h]hrustdoc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh# will create a link automatically).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jMhjJhhhhhNubjN)}(hXqAny ``unsafe`` block must be preceded by a ``// SAFETY:`` comment describing why the code inside is sound. While sometimes the reason might look trivial and therefore unneeded, writing these comments is not just a good way of documenting what has been taken into account, but most importantly, it provides a way to know that there are no *extra* implicit constraints. h](h)}(hjAny ``unsafe`` block must be preceded by a ``// SAFETY:`` comment describing why the code inside is sound.h](hAny }(hj3hhhNhNubj)}(h ``unsafe``h]hunsafe}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3ubh block must be preceded by a }(hj3hhhNhNubj)}(h``// SAFETY:``h]h // SAFETY:}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3ubh1 comment describing why the code inside is sound.}(hj3hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj/ubh)}(hXWhile sometimes the reason might look trivial and therefore unneeded, writing these comments is not just a good way of documenting what has been taken into account, but most importantly, it provides a way to know that there are no *extra* implicit constraints.h](hWhile sometimes the reason might look trivial and therefore unneeded, writing these comments is not just a good way of documenting what has been taken into account, but most importantly, it provides a way to know that there are no }(hjehhhNhNubhemphasis)}(h*extra*h]hextra}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjeubh implicit constraints.}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj/ubeh}(h]h ]h"]h$]h&]uh1jMhjJhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jHhhhKhjhhubh)}(hzTo learn more about how to write documentation for Rust and extra features, please take a look at the ``rustdoc`` book at:h](hfTo learn more about how to write documentation for Rust and extra features, please take a look at the }(hjhhhNhNubj)}(h ``rustdoc``h]hrustdoc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh book at:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hBhttps://doc.rust-lang.org/rustdoc/how-to-write-documentation.html h]h)}(hAhttps://doc.rust-lang.org/rustdoc/how-to-write-documentation.htmlh]j)}(hjh]hAhttps://doc.rust-lang.org/rustdoc/how-to-write-documentation.html}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhM hjubah}(h]h ]h"]h$]h&]uh1jhhhM hjhhubh)}(hIn addition, the kernel supports creating links relative to the source tree by prefixing the link destination with ``srctree/``. For instance:h](hsIn addition, the kernel supports creating links relative to the source tree by prefixing the link destination with }(hjhhhNhNubj)}(h ``srctree/``h]hsrctree/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. For instance:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjhhubj{)}(hH//! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)h]hH//! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)}hjsbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMhjhhubh)}(hor:h]hor:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj{)}(h3/// [`struct mutex`]: srctree/include/linux/mutex.hh]h3/// [`struct mutex`]: srctree/include/linux/mutex.h}hjsbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMhjhhubeh}(h]code-documentationah ]h"]code documentationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h C FFI typesh]h C FFI types}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj-hhhhhMubh)}(hRust kernel code refers to C types, such as ``int``, using type aliases such as ``c_int``, which are readily available from the ``kernel`` prelude. Please do not use the aliases from ``core::ffi`` -- they may not map to the correct types.h](h,Rust kernel code refers to C types, such as }(hj>hhhNhNubj)}(h``int``h]hint}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj>ubh, using type aliases such as }(hj>hhhNhNubj)}(h ``c_int``h]hc_int}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj>ubh', which are readily available from the }(hj>hhhNhNubj)}(h ``kernel``h]hkernel}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj>ubh- prelude. Please do not use the aliases from }(hj>hhhNhNubj)}(h ``core::ffi``h]h core::ffi}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj>ubh* -- they may not map to the correct types.}(hj>hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj-hhubh)}(huThese aliases should generally be referred directly by their identifier, i.e. as a single segment path. For instance:h]huThese aliases should generally be referred directly by their identifier, i.e. as a single segment path. For instance:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj-hhubj{)}(h.fn f(p: *const c_char) -> c_int { // ... }h]h.fn f(p: *const c_char) -> c_int { // ... }}hjsbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhM#hj-hhubeh}(h] c-ffi-typesah ]h"] c ffi typesah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hNamingh]hNaming}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM+ubh)}(h;Rust kernel code follows the usual Rust naming conventions:h]h;Rust kernel code follows the usual Rust naming conventions:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hjhhubj)}(h7https://rust-lang.github.io/api-guidelines/naming.html h]h)}(h6https://rust-lang.github.io/api-guidelines/naming.htmlh]j)}(hjh]h6https://rust-lang.github.io/api-guidelines/naming.html}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhM/hjubah}(h]h ]h"]h$]h&]uh1jhhhM/hjhhubh)}(hXnWhen existing C concepts (e.g. macros, functions, objects...) are wrapped into a Rust abstraction, a name as close as reasonably possible to the C side should be used in order to avoid confusion and to improve readability when switching back and forth between the C and Rust sides. For instance, macros such as ``pr_info`` from C are named the same in the Rust side.h](hX7When existing C concepts (e.g. macros, functions, objects...) are wrapped into a Rust abstraction, a name as close as reasonably possible to the C side should be used in order to avoid confusion and to improve readability when switching back and forth between the C and Rust sides. For instance, macros such as }(hjhhhNhNubj)}(h ``pr_info``h]hpr_info}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, from C are named the same in the Rust side.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM1hjhhubh)}(hHaving said that, casing should be adjusted to follow the Rust naming conventions, and namespacing introduced by modules and types should not be repeated in the item names. For instance, when wrapping constants like:h]hHaving said that, casing should be adjusted to follow the Rust naming conventions, and namespacing introduced by modules and types should not be repeated in the item names. For instance, when wrapping constants like:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM7hjhhubj{)}(hC#define GPIO_LINE_DIRECTION_IN 0 #define GPIO_LINE_DIRECTION_OUT 1h]hC#define GPIO_LINE_DIRECTION_IN 0 #define GPIO_LINE_DIRECTION_OUT 1}hj)sbah}(h]h ]h"]h$]h&]hhjjcj}uh1jzhhhM;hjhhubh)}(h>The equivalent in Rust may look like (ignoring documentation):h]h>The equivalent in Rust may look like (ignoring documentation):}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hjhhubj{)}(hpub mod gpio { pub enum LineDirection { In = bindings::GPIO_LINE_DIRECTION_IN as _, Out = bindings::GPIO_LINE_DIRECTION_OUT as _, } }h]hpub mod gpio { pub enum LineDirection { In = bindings::GPIO_LINE_DIRECTION_IN as _, Out = bindings::GPIO_LINE_DIRECTION_OUT as _, } }}hjGsbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMBhjhhubh)}(hThat is, the equivalent of ``GPIO_LINE_DIRECTION_IN`` would be referred to as ``gpio::LineDirection::In``. In particular, it should not be named ``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``.h](hThat is, the equivalent of }(hjWhhhNhNubj)}(h``GPIO_LINE_DIRECTION_IN``h]hGPIO_LINE_DIRECTION_IN}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjWubh would be referred to as }(hjWhhhNhNubj)}(h``gpio::LineDirection::In``h]hgpio::LineDirection::In}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjWubh(. In particular, it should not be named }(hjWhhhNhNubj)}(h5``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``h]h1gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjWubh.}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMKhjhhubeh}(h]namingah ]h"]namingah$]h&]uh1hhhhhhhhM+ubh)}(hhh](h)}(hLintsh]hLints}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMQubh)}(hIn Rust, it is possible to ``allow`` particular warnings (diagnostics, lints) locally, making the compiler ignore instances of a given warning within a given function, module, block, etc.h](hIn Rust, it is possible to }(hjhhhNhNubj)}(h ``allow``h]hallow}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh particular warnings (diagnostics, lints) locally, making the compiler ignore instances of a given warning within a given function, module, block, etc.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMShjhhubh)}(hSIt is similar to ``#pragma GCC diagnostic push`` + ``ignored`` + ``pop`` in C [#]_:h](hIt is similar to }(hjhhhNhNubj)}(h``#pragma GCC diagnostic push``h]h#pragma GCC diagnostic push}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh + }(hjhhhNhNubj)}(h ``ignored``h]hignored}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh + }hjsbj)}(h``pop``h]hpop}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh in C }(hjhhhNhNubhfootnote_reference)}(h[#]_h]h1}(hj hhhNhNubah}(h]id1ah ]h"]h$]h&]autoKrefidid2docnamerust/coding-guidelinesuh1j hjresolvedKubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMWhjhhubj{)}(h#pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wunused-function" static void f(void) {} #pragma GCC diagnostic poph]h#pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wunused-function" static void f(void) {} #pragma GCC diagnostic pop}hj3 sbah}(h]h ]h"]h$]h&]hhjjj7j}uh1jzhhhMZhjhhubhfootnote)}(hIn this particular case, the kernel's ``__{always,maybe}_unused`` attributes (C23's ``[[maybe_unused]]``) may be used; however, the example is meant to reflect the equivalent lint in Rust discussed afterwards. h](hlabel)}(hhh]h1}(hjJ hhhNhNubah}(h]h ]h"]h$]h&]uh1jH hjD hhhNhNubh)}(hIn this particular case, the kernel's ``__{always,maybe}_unused`` attributes (C23's ``[[maybe_unused]]``) may be used; however, the example is meant to reflect the equivalent lint in Rust discussed afterwards.h](h(In this particular case, the kernel’s }(hjW hhhNhNubj)}(h``__{always,maybe}_unused``h]h__{always,maybe}_unused}(hj_ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjW ubh attributes (C23’s }(hjW hhhNhNubj)}(h``[[maybe_unused]]``h]h[[maybe_unused]]}(hjq hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjW ubhi) may be used; however, the example is meant to reflect the equivalent lint in Rust discussed afterwards.}(hjW hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMahjD ubeh}(h]j% ah ]h"]1ah$]h&]j aj# Kj& j' uh1jB hhhMahjhhubh)}(hBut way less verbose:h]hBut way less verbose:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMehjhhubj{)}(h#[allow(dead_code)] fn f() {}h]h#[allow(dead_code)] fn f() {}}hj sbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMghjhhubh)}(hBy that virtue, it makes it possible to comfortably enable more diagnostics by default (i.e. outside ``W=`` levels). In particular, those that may have some false positives but that are otherwise quite useful to keep enabled to catch potential mistakes.h](heBy that virtue, it makes it possible to comfortably enable more diagnostics by default (i.e. outside }(hj hhhNhNubj)}(h``W=``h]hW=}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh levels). In particular, those that may have some false positives but that are otherwise quite useful to keep enabled to catch potential mistakes.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMlhjhhubh)}(hXOn top of that, Rust provides the ``expect`` attribute which takes this further. It makes the compiler warn if the warning was not produced. For instance, the following will ensure that, when ``f()`` is called somewhere, we will have to remove the attribute:h](h"On top of that, Rust provides the }(hj hhhNhNubj)}(h ``expect``h]hexpect}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh attribute which takes this further. It makes the compiler warn if the warning was not produced. For instance, the following will ensure that, when }(hj hhhNhNubj)}(h``f()``h]hf()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh; is called somewhere, we will have to remove the attribute:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMqhjhhubj{)}(h#[expect(dead_code)] fn f() {}h]h#[expect(dead_code)] fn f() {}}hj sbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMvhjhhubh)}(h2If we do not, we get a warning from the compiler::h]h1If we do not, we get a warning from the compiler:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM{hjhhubj{)}(hwarning: this lint expectation is unfulfilled --> x.rs:3:10 | 3 | #[expect(dead_code)] | ^^^^^^^^^ | = note: `#[warn(unfulfilled_lint_expectations)]` on by defaulth]hwarning: this lint expectation is unfulfilled --> x.rs:3:10 | 3 | #[expect(dead_code)] | ^^^^^^^^^ | = note: `#[warn(unfulfilled_lint_expectations)]` on by default}hj sbah}(h]h ]h"]h$]h&]hhuh1jzhhhM}hjhhubh)}(hzThis means that ``expect``\ s do not get forgotten when they are not needed, which may happen in several situations, e.g.:h](hThis means that }(hj, hhhNhNubj)}(h ``expect``h]hexpect}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj, ubh` s do not get forgotten when they are not needed, which may happen in several situations, e.g.:}(hj, hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubjI)}(hhh](jN)}(h-Temporary attributes added while developing. h]h)}(h,Temporary attributes added while developing.h]h,Temporary attributes added while developing.}(hjS hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjO ubah}(h]h ]h"]h$]h&]uh1jMhjL hhhhhNubjN)}(haImprovements in lints in the compiler, Clippy or custom tools which may remove a false positive. h]h)}(h`Improvements in lints in the compiler, Clippy or custom tools which may remove a false positive.h]h`Improvements in lints in the compiler, Clippy or custom tools which may remove a false positive.}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjg ubah}(h]h ]h"]h$]h&]uh1jMhjL hhhhhNubjN)}(hWhen the lint is not needed anymore because it was expected that it would be removed at some point, such as the ``dead_code`` example above. h]h)}(hWhen the lint is not needed anymore because it was expected that it would be removed at some point, such as the ``dead_code`` example above.h](hpWhen the lint is not needed anymore because it was expected that it would be removed at some point, such as the }(hj hhhNhNubj)}(h ``dead_code``h]h dead_code}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh example above.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jMhjL hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jHhhhMhjhhubh)}(hiIt also increases the visibility of the remaining ``allow``\ s and reduces the chance of misapplying one.h](h2It also increases the visibility of the remaining }(hj hhhNhNubj)}(h ``allow``h]hallow}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh. s and reduces the chance of misapplying one.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h-Thus prefer ``expect`` over ``allow`` unless:h](h Thus prefer }(hj hhhNhNubj)}(h ``expect``h]hexpect}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh over }(hj hhhNhNubj)}(h ``allow``h]hallow}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh unless:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubjI)}(hhh](jN)}(hXUConditional compilation triggers the warning in some cases but not others. If there are only a few cases where the warning triggers (or does not trigger) compared to the total number of cases, then one may consider using a conditional ``expect`` (i.e. ``cfg_attr(..., expect(...))``). Otherwise, it is likely simpler to just use ``allow``. h](h)}(hJConditional compilation triggers the warning in some cases but not others.h]hJConditional compilation triggers the warning in some cases but not others.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hXIf there are only a few cases where the warning triggers (or does not trigger) compared to the total number of cases, then one may consider using a conditional ``expect`` (i.e. ``cfg_attr(..., expect(...))``). Otherwise, it is likely simpler to just use ``allow``.h](hIf there are only a few cases where the warning triggers (or does not trigger) compared to the total number of cases, then one may consider using a conditional }(hj hhhNhNubj)}(h ``expect``h]hexpect}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh (i.e. }(hj hhhNhNubj)}(h``cfg_attr(..., expect(...))``h]hcfg_attr(..., expect(...))}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh/). Otherwise, it is likely simpler to just use }(hj hhhNhNubj)}(h ``allow``h]hallow}(hjB hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jMhj hhhhhNubjN)}(hInside macros, when the different invocations may create expanded code that triggers the warning in some cases but not in others. h]h)}(hInside macros, when the different invocations may create expanded code that triggers the warning in some cases but not in others.h]hInside macros, when the different invocations may create expanded code that triggers the warning in some cases but not in others.}(hjd hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj` ubah}(h]h ]h"]h$]h&]uh1jMhj hhhhhNubjN)}(hoWhen code may trigger a warning for some architectures but not others, such as an ``as`` cast to a C FFI type. h]h)}(hnWhen code may trigger a warning for some architectures but not others, such as an ``as`` cast to a C FFI type.h](hRWhen code may trigger a warning for some architectures but not others, such as an }(hj| hhhNhNubj)}(h``as``h]has}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj| ubh cast to a C FFI type.}(hj| hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjx ubah}(h]h ]h"]h$]h&]uh1jMhj hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jHhhhMhjhhubh)}(h@As a more developed example, consider for instance this program:h]h@As a more developed example, consider for instance this program:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj{)}(h6fn g() {} fn main() { #[cfg(CONFIG_X)] g(); }h]h6fn g() {} fn main() { #[cfg(CONFIG_X)] g(); }}hj sbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMhjhhubh)}(h[Here, function ``g()`` is dead code if ``CONFIG_X`` is not set. Can we use ``expect`` here?h](hHere, function }(hj hhhNhNubj)}(h``g()``h]hg()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh is dead code if }(hj hhhNhNubj)}(h ``CONFIG_X``h]hCONFIG_X}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh is not set. Can we use }(hj hhhNhNubj)}(h ``expect``h]hexpect}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh here?}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj{)}(hK#[expect(dead_code)] fn g() {} fn main() { #[cfg(CONFIG_X)] g(); }h]hK#[expect(dead_code)] fn g() {} fn main() { #[cfg(CONFIG_X)] g(); }}hj sbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMhjhhubh)}(hThis would emit a lint if ``CONFIG_X`` is set, since it is not dead code in that configuration. Therefore, in cases like this, we cannot use ``expect`` as-is.h](hThis would emit a lint if }(hj hhhNhNubj)}(h ``CONFIG_X``h]hCONFIG_X}(hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhg is set, since it is not dead code in that configuration. Therefore, in cases like this, we cannot use }(hj hhhNhNubj)}(h ``expect``h]hexpect}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh as-is.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h(A simple possibility is using ``allow``:h](hA simple possibility is using }(hjL hhhNhNubj)}(h ``allow``h]hallow}(hjT hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjL ubh:}(hjL hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj{)}(hJ#[allow(dead_code)] fn g() {} fn main() { #[cfg(CONFIG_X)] g(); }h]hJ#[allow(dead_code)] fn g() {} fn main() { #[cfg(CONFIG_X)] g(); }}hjl sbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMhjhhubh)}(h7An alternative would be using a conditional ``expect``:h](h,An alternative would be using a conditional }(hj| hhhNhNubj)}(h ``expect``h]hexpect}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj| ubh:}(hj| hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj{)}(hd#[cfg_attr(not(CONFIG_X), expect(dead_code))] fn g() {} fn main() { #[cfg(CONFIG_X)] g(); }h]hd#[cfg_attr(not(CONFIG_X), expect(dead_code))] fn g() {} fn main() { #[cfg(CONFIG_X)] g(); }}hj sbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jzhhhMhjhhubh)}(hThis would ensure that, if someone introduces another call to ``g()`` somewhere (e.g. unconditionally), then it would be spotted that it is not dead code anymore. However, the ``cfg_attr`` is more complex than a simple ``allow``.h](h>This would ensure that, if someone introduces another call to }(hj hhhNhNubj)}(h``g()``h]hg()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhk somewhere (e.g. unconditionally), then it would be spotted that it is not dead code anymore. However, the }(hj hhhNhNubj)}(h ``cfg_attr``h]hcfg_attr}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh is more complex than a simple }(hj hhhNhNubj)}(h ``allow``h]hallow}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hTherefore, it is likely that it is not worth using conditional ``expect``\ s when more than one or two configurations are involved or when the lint may be triggered due to non-local changes (such as ``dead_code``).h](h?Therefore, it is likely that it is not worth using conditional }(hj hhhNhNubj)}(h ``expect``h]hexpect}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh~ s when more than one or two configurations are involved or when the lint may be triggered due to non-local changes (such as }(hj hhhNhNubj)}(h ``dead_code``h]h dead_code}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h;For more information about diagnostics in Rust, please see:h]h;For more information about diagnostics in Rust, please see:}(hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hGhttps://doc.rust-lang.org/stable/reference/attributes/diagnostics.html h]h)}(hFhttps://doc.rust-lang.org/stable/reference/attributes/diagnostics.htmlh]j)}(hj6 h]hFhttps://doc.rust-lang.org/stable/reference/attributes/diagnostics.html}(hj8 hhhNhNubah}(h]h ]h"]h$]h&]refurij6 uh1jhj4 ubah}(h]h ]h"]h$]h&]uh1hhhhMhj0 ubah}(h]h ]h"]h$]h&]uh1jhhhMhjhhubeh}(h]lintsah ]h"]lintsah$]h&]uh1hhhhhhhhMQubh)}(hhh](h)}(hError handlingh]hError handling}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZ hhhhhMubh)}(h\For some background and guidelines about Rust for Linux specific error handling, please see:h]h\For some background and guidelines about Rust for Linux specific error handling, please see:}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjZ hhubj)}(hThttps://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rusth]h)}(hj{ h]j)}(hj{ h]hThttps://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust}(hj hhhNhNubah}(h]h ]h"]h$]h&]refurij{ uh1jhj} ubah}(h]h ]h"]h$]h&]uh1hhhhMhjy ubah}(h]h ]h"]h$]h&]uh1jhhhMhjZ hhubeh}(h]error-handlingah ]h"]error handlingah$]h&]uh1hhhhhhhhMubeh}(h]coding-guidelinesah ]h"]coding guidelinesah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}j% ]j asnameids}(j j jjjjjjj*j'jjjjjW jT j j j j% u nametypes}(j jjjj*jjjW j j uh}(j hjhjjjjj'jjj-jjjT jj j j% jD j jZ u footnote_refs} citation_refs} autofootnotes]jD aautofootnote_refs]j asymbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j KsRparse_messages]transform_messages] transformerN include_log] decorationNhhub.