[PATCH v2] docs: Add documentation for ARC processors

[Jonathan Corbet]

Alexey Brodkin <Alexey.Brodkin at synopsys.com> writes:

> ARC processors are supported in upstream kernel since v3.9
> and so far there was no documentation about them except some
> Device Tree bindings.
>
> Fixing it with the simples set of docs now:
> 1. Overview with pointers to other informational resources
> 2. Autogenerated feature table
>
> Note though it's just the very beginning, there will be more
> for sure given time as there're many things worth documenting
> and in fact even contents itself is avaialble but just spread
> in some other places. Now we'll try to keep all here and
> then maintain it looking forward to match the state of development.
>
> Signed-off-by: Alexey Brodkin <abrodkin at synopsys.com>
> Cc: Randy Dunlap <rdunlap at infradead.org>
> Cc: Vineet Gupta <vgupta at kernel.org>

I've applied this set, but I have a couple of quibbles that it would be
nice to see addressed...

> Changes v1 -> v2:
>  * Spello "linux" -> "Linux" (Randy Dunlap)
>
>  Documentation/arc/arc.rst      | 81 ++++++++++++++++++++++++++++++++++
>  Documentation/arc/features.rst |  3 ++
>  Documentation/arc/index.rst    | 17 +++++++
>  Documentation/arch.rst         |  1 +
>  MAINTAINERS                    |  1 +
>  5 files changed, 103 insertions(+)
>  create mode 100644 Documentation/arc/arc.rst
>  create mode 100644 Documentation/arc/features.rst
>  create mode 100644 Documentation/arc/index.rst
>
> diff --git a/Documentation/arc/arc.rst b/Documentation/arc/arc.rst
> new file mode 100644
> index 000000000000..249d03c6be8e
> --- /dev/null
> +++ b/Documentation/arc/arc.rst
> @@ -0,0 +1,81 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Linux kernel for ARC processors
> +*******************************
> +
> +Other sources of information
> +############################
> +
> +Below are some resources where more information can be found on
> +ARC processors and relevant open source projects.
> +
> +1. `<https://embarc.org/>`_ - Community portal for open source on ARC.
> +Good place to start to find relevant FOSS projects, toolchain releases,
> +news items and more.
> +
> +2. `<https://github.com/foss-for-synopsys-dwc-arc-processors>`_ -
> +Home for all development activities regarding open source projects for
> +ARC processors. Some of the projects are forks of various upstream projects,
> +where "work in progress" is hosted prior to submission to upstream projects.
> +Other projects are developed by Synopsys and made available to community
> +as open source for use on ARC Processors.
> +
> +3. `<https://www.synopsys.com/designware-ip/processor-solutions.html>`_ -
> +Official Synopsys ARC Processors website location, with access to some IP
> +documentation (Programmer's Reference Manuals, AKA "PRM's", see
> +`<https://www.synopsys.com/dw/doc.php/ds/cc/programmers-reference-manual-ARC-HS.pdf>`_)

This manual requires registration (with a fair amount of information
required) to get.  That should at least be mentioned if we can't find a
less obnoxious version out there.

> +and commercial tools (Free nSIM,
> +`<https://www.synopsys.com/cgi-bin/dwarcnsim/req1.cgi>`_ and
> +MetaWare Light Edition, `<https://www.synopsys.com/cgi-bin/arcmwtk_lite/reg1.cgi>`_)
> +
> +Important note on ARC processors configurability
> +################################################
> +
> +ARC processors are highly configurable and several configurable options
> +are supported in Linux. Some options are transparent to software
> +(i.e cache geometries, some can be detected at runtime and configured
> +and used accordingly, while some need to be explicitly selected or configured
> +in the kernel's configuration utility (AKA "make menuconfig").
> +
> +However not all configurable options are supported when an ARC processor
> +is to run Linux. SoC design teams should refer to "Appendix E:
> +Configuration for ARC Linux" in the ARC HS Databook for configurability
> +guidelines.
> +
> +Following these guidelines and selecting valid configuration options
> +up front is critical to help prevent any unwanted issues during
> +SoC bringup and software development in general.
> +
> +Building the Linux kernel for ARC processors
> +############################################
> +
> +The process of kernel building for ARC processors is the same as for any other
> +architecture and could be done in 2 ways:
> +
> +1. cross-compilation: process of compiling for ARC targets on a development
> +host with a different processor architecture (generally x86_64/amd64).
> +
> +2. native compilation: process of compiling for ARC on a ARC platform
> +(hardware board or a simulator like QEMU) with complete development environment
> +(GNU toolchain, dtc, make etc) installed on the platform.

These enumerated lists would render a lot more pleasantly if you
actually formatted them as RST enumerated lists - with lines after the
first indented.

> +In both cases, up-to-date GNU toolchain for ARC for the host is needed.
> +Synopsys offers prebuilt toolchain releases which can be used for this purpose,
> +available from:
> +
> +1. Synopsys GNU toolchain releases:
> +`<https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases>`_
> +2. Linux kernel compilers collection:
> +`<https://mirrors.edge.kernel.org/pub/tools/crosstool/>`_
> +3. Bootlin's toolchain collection: `<https://toolchains.bootlin.com/>`_

These, in particular, render in a pretty ugly way.

Thanks,

jon