| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Date: Mon, 9 May 2022 13:02:08 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: ojeda@...nel.org
Cc: alex.gaynor@...il.com, ark.email@...il.com, bobo1239@....de,
bobwxc@...il.cn, corbet@....net, dxu@...uu.xyz, gary@...yguo.net,
gregkh@...uxfoundation.org, jarkko@...nel.org, jtitor@...6.org,
linux-doc@...r.kernel.org, linux-kbuild@...r.kernel.org,
linux-kernel@...r.kernel.org, masahiroy@...nel.org, me@...erkle.de,
me@...enk.de, michal.lkml@...kovi.net, mpe@...erman.id.au,
ndesaulniers@...gle.com, rust-for-linux@...r.kernel.org,
thesven73@...il.com, torvalds@...ux-foundation.org,
wedsonaf@...gle.com, wei.liu@...nel.org
Subject: Re: [PATCH v6 18/23] docs: add Rust documentation
Hi Miguel,
On Sat, 7 May 2022 07:24:16 +0200,
Miguel Ojeda wrote:
> Most of the documentation for Rust is written within the source code
> itself, as it is idiomatic for Rust projects. This applies to both
> the shared infrastructure at `rust/` as well as any other Rust module
> (e.g. drivers) written across the kernel.
>
> However, these documents contain general information that does not
> fit particularly well in the source code, like the Quick Start guide.
>
> It also contains an asset (SVG logo) used for the `rustdoc` target
> and a few other small changes elsewhere in the documentation folder.
>
> Co-developed-by: Alex Gaynor <alex.gaynor@...il.com>
> Signed-off-by: Alex Gaynor <alex.gaynor@...il.com>
> Co-developed-by: Finn Behrens <me@...enk.de>
> Signed-off-by: Finn Behrens <me@...enk.de>
> Co-developed-by: Adam Bratschi-Kaye <ark.email@...il.com>
> Signed-off-by: Adam Bratschi-Kaye <ark.email@...il.com>
> Co-developed-by: Wedson Almeida Filho <wedsonaf@...gle.com>
> Signed-off-by: Wedson Almeida Filho <wedsonaf@...gle.com>
> Co-developed-by: Michael Ellerman <mpe@...erman.id.au>
> Signed-off-by: Michael Ellerman <mpe@...erman.id.au>
> Co-developed-by: Sven Van Asbroeck <thesven73@...il.com>
> Signed-off-by: Sven Van Asbroeck <thesven73@...il.com>
> Co-developed-by: Wu XiangCheng <bobwxc@...il.cn>
> Signed-off-by: Wu XiangCheng <bobwxc@...il.cn>
> Co-developed-by: Gary Guo <gary@...yguo.net>
> Signed-off-by: Gary Guo <gary@...yguo.net>
> Co-developed-by: Boris-Chengbiao Zhou <bobo1239@....de>
> Signed-off-by: Boris-Chengbiao Zhou <bobo1239@....de>
> Co-developed-by: Yuki Okushi <jtitor@...6.org>
> Signed-off-by: Yuki Okushi <jtitor@...6.org>
> Co-developed-by: Wei Liu <wei.liu@...nel.org>
> Signed-off-by: Wei Liu <wei.liu@...nel.org>
> Co-developed-by: Daniel Xu <dxu@...uu.xyz>
> Signed-off-by: Daniel Xu <dxu@...uu.xyz>
> Co-developed-by: Julian Merkle <me@...erkle.de>
> Signed-off-by: Julian Merkle <me@...erkle.de>
> Signed-off-by: Miguel Ojeda <ojeda@...nel.org>
> ---
> Documentation/doc-guide/kernel-doc.rst | 3 +
> Documentation/index.rst | 1 +
> Documentation/kbuild/kbuild.rst | 17 +
> Documentation/kbuild/makefiles.rst | 50 ++-
> Documentation/process/changes.rst | 41 +++
> Documentation/rust/arch-support.rst | 34 ++
> Documentation/rust/coding-guidelines.rst | 214 ++++++++++++
> Documentation/rust/general-information.rst | 77 +++++
> Documentation/rust/index.rst | 20 ++
> Documentation/rust/logo.svg | 357 +++++++++++++++++++++
I think you agreed splitting SVG part into its own patch with
a proper copying info, etc. Let me see... So, here is the link:
https://lore.kernel.org/lkml/CANiq72mLtvWJ5peSTpYQ8AeLEskga6Pda8Q7Daysv2pfycnyxA@mail.gmail.com/
I might have missed v5 of this patch series.
That might be because v5's 15/20 was not accepted by linux-doc's
lore archive (maybe) due to its size despite it had Cc: linux-doc.
v6's 18/23 was also rejected.
> Documentation/rust/quick-start.rst | 230 +++++++++++++
> 11 files changed, 1040 insertions(+), 4 deletions(-)
> create mode 100644 Documentation/rust/arch-support.rst
> create mode 100644 Documentation/rust/coding-guidelines.rst
> create mode 100644 Documentation/rust/general-information.rst
> create mode 100644 Documentation/rust/index.rst
> create mode 100644 Documentation/rust/logo.svg
> create mode 100644 Documentation/rust/quick-start.rst
I have some alternative ideas for table formatting in ReST.
> diff --git a/Documentation/rust/arch-support.rst b/Documentation/rust/arch-support.rst
> new file mode 100644
> index 000000000000..482757a1f3d0
> --- /dev/null
> +++ b/Documentation/rust/arch-support.rst
> @@ -0,0 +1,34 @@
> +Arch Support
> +============
> +
> +Currently, the Rust compiler (``rustc``) uses LLVM for code generation,
> +which limits the supported architectures that can be targeted. In addition,
> +support for building the kernel with LLVM/Clang varies (please see
> +Documentation/kbuild/llvm.rst). This support is needed for ``bindgen``
> +which uses ``libclang``.
> +
> +Below is a general summary of architectures that currently work. Level of
> +support corresponds to ``S`` values in the ``MAINTAINERS`` file.
> +
> +.. list-table::
> + :widths: 10 10 10
> + :header-rows: 1
> +
> + * - Architecture
> + - Level of support
> + - Constraints
> + * - ``arm``
> + - Maintained
> + - ``armv6`` and compatible only, ``RUST_OPT_LEVEL >= 2``
> + * - ``arm64``
> + - Maintained
> + - None
> + * - ``powerpc``
> + - Maintained
> + - ``ppc64le`` only, ``RUST_OPT_LEVEL < 2`` requires ``CONFIG_THREAD_SHIFT=15``
> + * - ``riscv``
> + - Maintained
> + - ``riscv64`` only
> + * - ``x86``
> + - Maintained
> + - ``x86_64`` only
Excerpt from Section "list tables" in
Documentation/doc-guide/sphinx.rst:
> The list-table formats can be useful for tables that are not easily laid
> out in the usual Sphinx ASCII-art formats. These formats are nearly
> impossible for readers of the plain-text documents to understand, though,
> and should be avoided in the absence of a strong justification for their
> use.
So here are a couple of alternative ways to represent the table
* ASCII-art format:
============ ================ ==========================================
Architecture Level of support Constraints
============ ================ ==========================================
``arm`` Maintained ``armv6`` and compatible only,
``RUST_OPT_LEVEL >= 2``
``arm64`` Maintained None
``powerpc`` Maintained ``ppc64le`` only, ``RUST_OPT_LEVEL < 2``
requires ``CONFIG_THREAD_SHIFT=15``
``riscv`` Maintained ``riscv64`` only
``x86`` Maintained ``x86_64`` only
============ ================ ==========================================
* Literal block format:
::
Architecture Level of support Constraints
------------ ---------------- -------------------------------------
arm Maintained armv6 and compatible only,
RUST_OPT_LEVEL >= 2
arm64 Maintained None
powerpc Maintained ppc64le only, RUST_OPT_LEVEL < 2
requires CONFIG_THREAD_SHIFT=15
riscv Maintained riscv64 only
x86 Maintained x86_64 only
"::" above the table marks the start of a literal block.
Indents are important for la iteral block to work.
A literal block ends at a line which has the same indent as
the preceding paragraph, in this case with no indent, or at
the end of file.
As you see, those inline-literal markers of ``xxxx``, which are
distracting when the .rst file is read as plain-text, are not
necessary in the literal-block approach. And you can directly
tweak line breaks in the Constraints column in the final HTML
and PDF docs.
In my opinion, the literal-block approach should be the most
reasonable choice here. Of course its your call which one
to choose.
Thanks, Akira
Powered by blists - more mailing lists