csphinx.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/general-informationmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/zh_TW/rust/general-informationmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/it_IT/rust/general-informationmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/ja_JP/rust/general-informationmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/ko_KR/rust/general-informationmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/sp_SP/rust/general-informationmodnameN 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:spacepreserveuh1hhhhhhF/var/lib/git/docbuild/linux/Documentation/rust/general-information.rsthKubhsection)}(hhh](htitle)}(hGeneral Informationh]hGeneral Information}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hcThis document contains useful information to know when working with the Rust support in the kernel.h]hcThis document contains useful information to know when working with the Rust support in the kernel.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h ``no_std``h]hliteral)}(hhh]hno_std}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh)}(hThe Rust support in the kernel can link only `core `_, but not `std `_. Crates for use in the kernel must opt into this behavior using the ``#![no_std]`` attribute.h](h-The Rust support in the kernel can link only }(hhhhhNhNubh reference)}(h)`core `_h]hcore}(hhhhhNhNubah}(h]h ]h"]h$]h&]namecorerefurihttps://doc.rust-lang.org/core/uh1hhhubhtarget)}(h" h]h}(h]coreah ]h"]coreah$]h&]refurijuh1j referencedKhhubh , but not }(hhhhhNhNubh)}(h'`std `_h]hstd}(hj%hhhNhNubah}(h]h ]h"]h$]h&]namestdjhttps://doc.rust-lang.org/std/uh1hhhubj)}(h! h]h}(h]stdah ]h"]stdah$]h&]refurij5uh1jj KhhubhE. Crates for use in the kernel must opt into this behavior using the }(hhhhhNhNubh)}(h``#![no_std]``h]h #![no_std]}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh attribute.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubj)}(h.. _rust_code_documentation:h]h}(h]h ]h"]h$]h&]refidrust-code-documentationuh1jhKhhhhhhubeh}(h]no-stdah ]h"]no_stdah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(hCode documentationh]hCode documentation}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjshhhhhKubh)}(hWRust kernel code is documented using ``rustdoc``, its built-in documentation generator.h](h%Rust kernel code is documented using }(hjhhhNhNubh)}(h ``rustdoc``h]hrustdoc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh', its built-in documentation generator.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjshhubh)}(hThe generated HTML docs include integrated search, linked items (e.g. types, functions, constants), source code, etc. They may be read at:h]hThe generated HTML docs include integrated search, linked items (e.g. types, functions, constants), source code, etc. They may be read at:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubh block_quote)}(hhttps://rust.docs.kernel.org h]h)}(hhttps://rust.docs.kernel.orgh]h)}(hjh]hhttps://rust.docs.kernel.org}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1hhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjshhubh)}(hFor linux-next, please see:h]hFor linux-next, please see:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubj)}(h#https://rust.docs.kernel.org/next/ h]h)}(h"https://rust.docs.kernel.org/next/h]h)}(hjh]h"https://rust.docs.kernel.org/next/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1hhjubah}(h]h ]h"]h$]h&]uh1hhhhK!hjubah}(h]h ]h"]h$]h&]uh1jhhhK!hjshhubh)}(h0There are also tags for each main release, e.g.:h]h0There are also tags for each main release, e.g.:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hjshhubj)}(h#https://rust.docs.kernel.org/6.10/ h]h)}(h"https://rust.docs.kernel.org/6.10/h]h)}(hjh]h"https://rust.docs.kernel.org/6.10/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1hhjubah}(h]h ]h"]h$]h&]uh1hhhhK%hjubah}(h]h ]h"]h$]h&]uh1jhhhK%hjshhubh)}(hXlThe docs can also be easily generated and read locally. This is quite fast (same order as compiling the code itself) and no special tools or environment are needed. This has the added advantage that they will be tailored to the particular kernel configuration used. To generate them, use the ``rustdoc`` target with the same invocation used for compilation, e.g.::h](hX$The docs can also be easily generated and read locally. This is quite fast (same order as compiling the code itself) and no special tools or environment are needed. This has the added advantage that they will be tailored to the particular kernel configuration used. To generate them, use the }(hj6hhhNhNubh)}(h ``rustdoc``h]hrustdoc}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubh< target with the same invocation used for compilation, e.g.:}(hj6hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK'hjshhubh literal_block)}(hmake LLVM=1 rustdoch]hmake LLVM=1 rustdoc}hjXsbah}(h]h ]h"]h$]h&]hhuh1jVhhhK-hjshhubh)}(h8To read the docs locally in your web browser, run e.g.::h]h7To read the docs locally in your web browser, run e.g.:}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK/hjshhubjW)}(h from the C side and calls its functions through the bindings.}(hjChhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKLhjhhubh)}(hX Abstractions are not available for all the kernel internal APIs and concepts, but it is intended that coverage is expanded as time goes on. "Leaf" modules (e.g. drivers) should not use the C bindings directly. Instead, subsystems should provide as-safe-as-possible abstractions as needed.h]hX$Abstractions are not available for all the kernel internal APIs and concepts, but it is intended that coverage is expanded as time goes on. “Leaf” modules (e.g. drivers) should not use the C bindings directly. Instead, subsystems should provide as-safe-as-possible abstractions as needed.}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjhhubjW)}(hX rust/bindings/ (rust/helpers/) include/ -----+ <-+ | | drivers/ rust/kernel/ +----------+ <-+ | fs/ | bindgen | | .../ +-------------------+ +----------+ --+ | | Abstractions | | | +---------+ | +------+ +------+ | +----------+ | | | my_foo | -----> | | foo | | bar | | -------> | Bindings | <-+ | | driver | Safe | | sub- | | sub- | | Unsafe | | | +---------+ | |system| |system| | | bindings | <-----+ | | +------+ +------+ | | crate | | | | kernel crate | +----------+ | | +-------------------+ | | | +------------------# FORBIDDEN #--------------------------------+h]hX rust/bindings/ (rust/helpers/) include/ -----+ <-+ | | drivers/ rust/kernel/ +----------+ <-+ | fs/ | bindgen | | .../ +-------------------+ +----------+ --+ | | Abstractions | | | +---------+ | +------+ +------+ | +----------+ | | | my_foo | -----> | | foo | | bar | | -------> | Bindings | <-+ | | driver | Safe | | sub- | | sub- | | Unsafe | | | +---------+ | |system| |system| | | bindings | <-----+ | | +------+ +------+ | | crate | | | | kernel crate | +----------+ | | +-------------------+ | | | +------------------# FORBIDDEN #--------------------------------+}hjsbah}(h]h ]h"]h$]h&]hhforcelanguagenonehighlight_args}uh1jVhhhKThjhhubh)}(hThe main idea is to encapsulate all direct interaction with the kernel's C APIs into carefully reviewed and documented abstractions. Then users of these abstractions cannot introduce undefined behavior (UB) as long as:h]hThe main idea is to encapsulate all direct interaction with the kernel’s C APIs into carefully reviewed and documented abstractions. Then users of these abstractions cannot introduce undefined behavior (UB) as long as:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKihjhhubhenumerated_list)}(hhh](h list_item)}(h'The abstractions are correct ("sound").h]h)}(hjh]h+The abstractions are correct (“sound”).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKmhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hAny ``unsafe`` blocks respect the safety contract necessary to call the operations inside the block. Similarly, any ``unsafe impl``\ s respect the safety contract necessary to implement the trait. h]h)}(hAny ``unsafe`` blocks respect the safety contract necessary to call the operations inside the block. Similarly, any ``unsafe impl``\ s respect the safety contract necessary to implement the trait.h](hAny }(hjhhhNhNubh)}(h ``unsafe``h]hunsafe}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhf blocks respect the safety contract necessary to call the operations inside the block. Similarly, any }(hjhhhNhNubh)}(h``unsafe impl``h]h unsafe impl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhA s respect the safety contract necessary to implement the trait.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKnhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhjhhhhhKmubh)}(hhh](h)}(hBindingsh]hBindings}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKsubh)}(hXBy including a C header from ``include/`` into ``rust/bindings/bindings_helper.h``, the ``bindgen`` tool will auto-generate the bindings for the included subsystem. After building, see the ``*_generated.rs`` output files in the ``rust/bindings/`` directory.h](hBy including a C header from }(hjhhhNhNubh)}(h ``include/``h]hinclude/}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh into }(hjhhhNhNubh)}(h#``rust/bindings/bindings_helper.h``h]hrust/bindings/bindings_helper.h}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh, the }(hjhhhNhNubh)}(h ``bindgen``h]hbindgen}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhZ tool will auto-generate the bindings for the included subsystem. After building, see the }(hjhhhNhNubh)}(h``*_generated.rs``h]h*_generated.rs}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh output files in the }(hjhhhNhNubh)}(h``rust/bindings/``h]hrust/bindings/}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh directory.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKuhj hhubh)}(hFor parts of the C header that ``bindgen`` does not auto generate, e.g. C ``inline`` functions or non-trivial macros, it is acceptable to add a small wrapper function to ``rust/helpers/`` to make it available for the Rust side as well.h](hFor parts of the C header that }(hjhhhNhNubh)}(h ``bindgen``h]hbindgen}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh does not auto generate, e.g. C }(hjhhhNhNubh)}(h ``inline``h]hinline}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhV functions or non-trivial macros, it is acceptable to add a small wrapper function to }(hjhhhNhNubh)}(h``rust/helpers/``h]h rust/helpers/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh0 to make it available for the Rust side as well.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKzhj hhubeh}(h]bindingsah ]h"]bindingsah$]h&]uh1hhjhhhhhKsubh)}(hhh](h)}(h Abstractionsh]h Abstractions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXHAbstractions are the layer between the bindings and the in-kernel users. They are located in ``rust/kernel/`` and their role is to encapsulate the unsafe access to the bindings into an as-safe-as-possible API that they expose to their users. Users of the abstractions include things like drivers or file systems written in Rust.h](h]Abstractions are the layer between the bindings and the in-kernel users. They are located in }(hjhhhNhNubh)}(h``rust/kernel/``h]h rust/kernel/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh and their role is to encapsulate the unsafe access to the bindings into an as-safe-as-possible API that they expose to their users. Users of the abstractions include things like drivers or file systems written in Rust.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX1Besides the safety aspect, the abstractions are supposed to be "ergonomic", in the sense that they turn the C interfaces into "idiomatic" Rust code. Basic examples are to turn the C resource acquisition and release into Rust constructors and destructors or C integer error codes into Rust's ``Result``\ s.h](hX-Besides the safety aspect, the abstractions are supposed to be “ergonomic”, in the sense that they turn the C interfaces into “idiomatic” Rust code. Basic examples are to turn the C resource acquisition and release into Rust constructors and destructors or C integer error codes into Rust’s }(hjhhhNhNubh)}(h ``Result``h]hResult}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh s.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] abstractionsah ]h"] abstractionsah$]h&]uh1hhjhhhhhKubeh}(h]abstractions-vs-bindingsah ]h"]abstractions vs. bindingsah$]h&]uh1hhhhhhhhKDubh)}(hhh](h)}(hConditional compilationh]hConditional compilation}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj/hhhhhKubh)}(hRRust code has access to conditional compilation based on the kernel configuration:h]hRRust code has access to conditional compilation based on the kernel configuration:}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj/hhubjW)}(h#[cfg(CONFIG_X)] // Enabled (`y` or `m`) #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`) #[cfg(CONFIG_X="m")] // Enabled as a module (`m`) #[cfg(not(CONFIG_X))] // Disabledh]h#[cfg(CONFIG_X)] // Enabled (`y` or `m`) #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`) #[cfg(CONFIG_X="m")] // Enabled as a module (`m`) #[cfg(not(CONFIG_X))] // Disabled}hjNsbah}(h]h ]h"]h$]h&]hhjjrustj}uh1jVhhhKhj/hhubh)}(hFor other predicates that Rust's ``cfg`` does not support, e.g. expressions with numerical comparisons, one may define a new Kconfig symbol:h](h#For other predicates that Rust’s }(hj^hhhNhNubh)}(h``cfg``h]hcfg}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^ubhd does not support, e.g. expressions with numerical comparisons, one may define a new Kconfig symbol:}(hj^hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj/hhubjW)}(hMconfig RUSTC_VERSION_MIN_107900 def_bool y if RUSTC_VERSION >= 107900h]hMconfig RUSTC_VERSION_MIN_107900 def_bool y if RUSTC_VERSION >= 107900}hj~sbah}(h]h ]h"]h$]h&]hhjjkconfigj}uh1jVhhhKhj/hhubeh}(h]conditional-compilationah ]h"]conditional compilationah$]h&]uh1hhhhhhhhKubeh}(h]general-informationah ]h"]general informationah$]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_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _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}jj]j_asnameids}(jjjpjmjjj?j<jjjjjjjj,j)jjj$j!jju nametypes}(jjpjj?jjjj,jj$juh}(jhjmhjjj<j6jjjsjjsjjj)jjj j!jjj/u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h=Hyperlink target "rust-code-documentation" is not referenced.}hj+sbah}(h]h ]h"]h$]h&]uh1hhj(ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKuh1j&uba transformerN include_log] decorationNhhub.