[v2] docs: Add documentation for ARC processors

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@synopsys.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Vineet Gupta <vgupta@kernel.org>
---

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

On 11/11/21 10:50 PM, Alexey Brodkin wrote:
> 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@synopsys.com>
> Cc: Randy Dunlap <rdunlap@infradead.org>
> Cc: Vineet Gupta <vgupta@kernel.org>
> ---
> 
> 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
> 

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

thanks.

Alexey Brodkin <Alexey.Brodkin@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@synopsys.com>
> Cc: Randy Dunlap <rdunlap@infradead.org>
> Cc: Vineet Gupta <vgupta@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

Hi Jonathan,
 
> > Signed-off-by: Alexey Brodkin <abrodkin@synopsys.com>
> > Cc: Randy Dunlap <rdunlap@infradead.org>
> > Cc: Vineet Gupta <vgupta@kernel.org>
> 
> I've applied this set, but I have a couple of quibbles that it would be
> nice to see addressed...

Thanks for taking care of that!

> > +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.

Well, I'm afraid that's the best we may get as of now. I wish is was available
with no registration whatsoever, but at least it could be easily had now by
wide audience.

Anyways, I'm wondering what kind of mention do you think is appropriate here?
Somehting like: "note, registration is required"?
 
> > +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.

Indeed, I'm much more used to Markdown and there it works ;)
So should I send a re-spin with fixed version?

 
> > +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://urldefense.com/v3/__https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases__;!!A4F2R9G_pg!N40JBI0hlr_f_ZX-pTGEO-vBvxNaA6NF4WYKA3yamILtuUOhgiEsFqRLfdx9VfetWmy7or8$ >`_
> > +2. Linux kernel compilers collection:
> > +`<https://urldefense.com/v3/__https://mirrors.edge.kernel.org/pub/tools/crosstool/__;!!A4F2R9G_pg!N40JBI0hlr_f_ZX-pTGEO-vBvxNaA6NF4WYKA3yamILtuUOhgiEsFqRLfdx9VfetayTOVRo$ >`_
> > +3. Bootlin's toolchain collection: `<https://urldefense.com/v3/__https://toolchains.bootlin.com/__;!!A4F2R9G_pg!N40JBI0hlr_f_ZX-pTGEO-vBvxNaA6NF4WYKA3yamILtuUOhgiEsFqRLfdx9Vfet7I-6RoI$ >`_
> 
> These, in particular, render in a pretty ugly way.

Right, here it gets even worse due to missing newlines. Again, fixed by:
-------------------------->8----------------------------
diff --git a/Documentation/arc/arc.rst b/Documentation/arc/arc.rst
index 249d03c6be8e..4dbd107f02e6 100644
--- a/Documentation/arc/arc.rst
+++ b/Documentation/arc/arc.rst
@@ -10,23 +10,23 @@ 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.
+   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.
+   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>`_)
-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>`_)
+   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>`_)
+   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
 ################################################
@@ -53,20 +53,22 @@ 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).
+   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.
+   (hardware board or a simulator like QEMU) with complete development environment
+   (GNU toolchain, dtc, make etc) installed on the platform.

 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>`_
+   `<https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases>`_
+
 2. Linux kernel compilers collection:
-`<https://mirrors.edge.kernel.org/pub/tools/crosstool/>`_
+   `<https://mirrors.edge.kernel.org/pub/tools/crosstool/>`_
+
 3. Bootlin's toolchain collection: `<https://toolchains.bootlin.com/>`_

 Once the toolchain is installed in the system, make sure its "bin" folder
-------------------------->8----------------------------

-Alexey

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

>> 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.
>
> Well, I'm afraid that's the best we may get as of now. I wish is was available
> with no registration whatsoever, but at least it could be easily had now by
> wide audience.
>
> Anyways, I'm wondering what kind of mention do you think is appropriate here?
> Somehting like: "note, registration is required"?

Something like that would be helpful, I think, yes.

>> > +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.
>
> Indeed, I'm much more used to Markdown and there it works ;)
> So should I send a re-spin with fixed version?

I applied the patch, so please send improvements on top of that.

Thanks,

jon