[OpenRISC] [PATCH 0/3] OpenRISC doc updates

[OpenRISC] [PATCH 0/3] OpenRISC doc updates

[Stafford Horne]

Hello,

This series moves OpenRISC documentation out of the arch/ folder and into the
Documentation folder.  I have also done some updates the README to bring to
better match the current state of OpenRISC.

Also, this adds documentation to the openrisc,or1ksim device tree binding which
was previously not documented.

Stafford Horne (3):
  Documentation: Move OpenRISC docs out of arch/
  Documentation: openrisc: Updates to README
  openrisc: dts: Add OpenRISC platform SoC

 .../bindings/openrisc/opencores/or1ksim.txt        | 39 +++++++++++++
 .../openrisc/README                                | 65 +++++++++++++---------
 .../TODO.openrisc => Documentation/openrisc/TODO   |  0
 MAINTAINERS                                        |  2 +
 4 files changed, 79 insertions(+), 27 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt
 rename arch/openrisc/README.openrisc => Documentation/openrisc/README (56%)
 rename arch/openrisc/TODO.openrisc => Documentation/openrisc/TODO (100%)

-- 
2.13.6

[OpenRISC] [PATCH 1/3] Documentation: Move OpenRISC docs out of arch/

[Stafford Horne]

The OpenRISC docs have traditionally been in arch/ but that does not
seem like the correct place to be.  Move them so they will be more
visible to others.  Also update MAINTAINERS to make sure we get
notifications of changes.

Signed-off-by: Stafford Horne <shorne@gmail.com>
---
 arch/openrisc/README.openrisc => Documentation/openrisc/README | 0
 arch/openrisc/TODO.openrisc => Documentation/openrisc/TODO     | 0
 MAINTAINERS                                                    | 1 +
 3 files changed, 1 insertion(+)
 rename arch/openrisc/README.openrisc => Documentation/openrisc/README (100%)
 rename arch/openrisc/TODO.openrisc => Documentation/openrisc/TODO (100%)

diff --git a/arch/openrisc/README.openrisc b/Documentation/openrisc/README
similarity index 100%
rename from arch/openrisc/README.openrisc
rename to Documentation/openrisc/README
diff --git a/arch/openrisc/TODO.openrisc b/Documentation/openrisc/TODO
similarity index 100%
rename from arch/openrisc/TODO.openrisc
rename to Documentation/openrisc/TODO
diff --git a/MAINTAINERS b/MAINTAINERS
index 8ce029872089..a57d13cb414d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10008,6 +10008,7 @@ T:	git git://github.com/openrisc/linux.git
 L:	openrisc at lists.librecores.org
 W:	http://openrisc.io
 S:	Maintained
+F:	Documentation/openrisc/
 F:	arch/openrisc/
 F:	drivers/irqchip/irq-or1k-*
 
-- 
2.13.6

[OpenRISC] [PATCH 2/3] Documentation: openrisc: Updates to README

[Stafford Horne]

Update the OpenRISC readme to provide some more up-to-date information
on how to get started with OpenRISC.  This includes:

 - remove references to southpole who no longer are consulting for
   OpenRISC (confirmed with Jonas)
 - suggested QEMU instead of the old or1ksim as QEMU is well supported
 - include instructions on how to get an FPGA board running

Suggested-by: Pavel Machek <pavel@ucw.cz>
Signed-off-by: Stafford Horne <shorne@gmail.com>
---
 Documentation/openrisc/README | 65 +++++++++++++++++++++++++------------------
 1 file changed, 38 insertions(+), 27 deletions(-)

diff --git a/Documentation/openrisc/README b/Documentation/openrisc/README
index 072069ab5100..777a893d533d 100644
--- a/Documentation/openrisc/README
+++ b/Documentation/openrisc/README
@@ -7,13 +7,7 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
 For information about OpenRISC processors and ongoing development:
 
 	website		http://openrisc.io
-
-For more information about Linux on OpenRISC, please contact South Pole AB.
-
-	email:		info at southpole.se
-
-	website:	http://southpole.se
-			http://southpoleconsulting.com
+	email		openrisc at lists.librecores.org
 
 ---------------------------------------------------------------------
 
@@ -24,37 +18,54 @@ In order to build and run Linux for OpenRISC, you'll need at least a basic
 toolchain and, perhaps, the architectural simulator.  Steps to get these bits
 in place are outlined here.
 
-1)  The toolchain can be obtained from openrisc.io.  Instructions for building
-a toolchain can be found at:
+1) Toolchain
+
+Toolchain binaries can be obtained from openrisc.io or our github releases page.
+Instructions for building the different toolchains can be found on openrisc.io
+or Stafford's toolchain build and release scripts.
+
+	binaries	https://github.com/openrisc/or1k-gcc/releases
+	toolchains	https://openrisc.io/software
+	building	https://github.com/stffrdhrn/or1k-toolchain-build
 
-https://github.com/openrisc/tutorials
+2) Building
 
-2) or1ksim (optional)
+Build the Linux kernel as usual
 
-or1ksim is the architectural simulator which will allow you to actually run
-your OpenRISC Linux kernel if you don't have an OpenRISC processor at hand.
+	make ARCH=openrisc defconfig
+	make ARCH=openrisc
 
-	git clone https://github.com/openrisc/or1ksim.git
+3) Running on FPGA (optional)
 
-	cd or1ksim
-	./configure --prefix=$OPENRISC_PREFIX
-	make
-	make install
+The OpenRISC community typically uses FuseSoC to manage building and programming
+an SoC into an FPGA.  The below is an example of programming a De0 Nano
+development board with the OpenRISC SoC.  During the build FPGA RTL is code
+downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
+tools.  Binaries are loaded onto the board with openocd.
 
-3)  Linux kernel
+	git clone https://github.com/olofk/fusesoc
+	cd fusesoc
+	sudo pip install -e .
 
-Build the kernel as usual
+	fusesoc init
+	fusesoc build de0_nano
+	fusesoc pgm de0_nano
 
-	make ARCH=openrisc defconfig
-	make ARCH=openrisc
+	openocd -f interface/altera-usb-blaster.cfg \
+		-f board/or1k_generic.cfg
+
+	telnet localhost 4444
+	> init
+	> halt; load_image vmlinux ; reset
 
-4)  Run in architectural simulator
+4) Running on a Simulator (optional)
 
-Grab the or1ksim platform configuration file (from the or1ksim source) and
-together with your freshly built vmlinux, run your kernel with the following
-incantation:
+QEMU is a processor emulator which we recommend for simulating the OpenRISC
+platform.  Please follow the OpenRISC instructions on the QEMU website to get
+Linux running on QEMU.  You can build QEMU yourself, but your Linux distribution
+likely provides binary packages to support OpenRISC.
 
-	sim -f arch/openrisc/or1ksim.cfg vmlinux
+	qemu openrisc	https://wiki.qemu.org/Documentation/Platforms/OpenRISC
 
 ---------------------------------------------------------------------
 
-- 
2.13.6

[OpenRISC] [PATCH 3/3] openrisc: dts: Add OpenRISC platform SoC

[Stafford Horne]

Add devicetree binding documentation for the OpenRISC platform
opencores,or1ksim.  This is the main OpenRISC reference platform
supporting multiple FPGA SoC's.

This format is based on some of the mips binding docs as we have
similar requirements.

Also, update maintainers so openrisc related binding changes are visible
to the openrisc team.

Suggested-by: Pavel Machek <pavel@ucw.cz>
Signed-off-by: Stafford Horne <shorne@gmail.com>
---
 .../bindings/openrisc/opencores/or1ksim.txt        | 39 ++++++++++++++++++++++
 MAINTAINERS                                        |  1 +
 2 files changed, 40 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt

diff --git a/Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt b/Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt
new file mode 100644
index 000000000000..4950c794ecbb
--- /dev/null
+++ b/Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt
@@ -0,0 +1,39 @@
+OpenRISC Generic SoC
+====================
+
+Boards and FPGA SoC's which support the OpenRISC standard platform.  The
+platform essentially follows the conventions of the OpenRISC architecture
+specification, however some aspects, such as the boot protocol have been defined
+by the Linux port.
+
+Required properties
+-------------------
+ - compatible: Must include "opencores,or1ksim"
+
+CPU nodes:
+----------
+A "cpus" node is required.  Required properties:
+ - #address-cells: Must be 1.
+ - #size-cells: Must be 0.
+A CPU sub-node is also required for at least CPU 0.  Since the topology may
+be probed via CPS, it is not necessary to specify secondary CPUs.  Required
+properties:
+ - compatible: Must be "opencores,or1200-rtlsvn481".
+ - reg: CPU number.
+ - clock-frequency: The CPU clock frequency in Hz.
+Example:
+	cpus {
+		#address-cells = <1>;
+		#size-cells = <0>;
+		cpu at 0 {
+			compatible = "opencores,or1200-rtlsvn481";
+			reg = <0>;
+			clock-frequency = <20000000>;
+		};
+	};
+
+
+Boot protocol
+-------------
+The bootloader may pass the following arguments to the kernel:
+ - r3:  address of a flattened device-tree blob or 0x0.
diff --git a/MAINTAINERS b/MAINTAINERS
index a57d13cb414d..71e4f6762196 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10008,6 +10008,7 @@ T:	git git://github.com/openrisc/linux.git
 L:	openrisc at lists.librecores.org
 W:	http://openrisc.io
 S:	Maintained
+F;	Documentation/devicetree/bindings/openrisc/
 F:	Documentation/openrisc/
 F:	arch/openrisc/
 F:	drivers/irqchip/irq-or1k-*
-- 
2.13.6

[OpenRISC] [PATCH 3/3] openrisc: dts: Add OpenRISC platform SoC

[Rob Herring]

On Sun, Oct 22, 2017 at 11:46:41AM +0900, Stafford Horne wrote:
> Add devicetree binding documentation for the OpenRISC platform
> opencores,or1ksim.  This is the main OpenRISC reference platform
> supporting multiple FPGA SoC's.
> 
> This format is based on some of the mips binding docs as we have
> similar requirements.
> 
> Also, update maintainers so openrisc related binding changes are visible
> to the openrisc team.

Your subject is wrong because this is not a dts patch. Use 
"dt-bindings: openrisc: ..."

> 
> Suggested-by: Pavel Machek <pavel@ucw.cz>
> Signed-off-by: Stafford Horne <shorne@gmail.com>
> ---
>  .../bindings/openrisc/opencores/or1ksim.txt        | 39 ++++++++++++++++++++++
>  MAINTAINERS                                        |  1 +
>  2 files changed, 40 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt

Otherwise,

Acked-by: Rob Herring <robh@kernel.org>

[OpenRISC] [PATCH 3/3] openrisc: dts: Add OpenRISC platform SoC

[Stafford Horne]

On Thu, Oct 26, 2017 at 10:18:33PM -0500, Rob Herring wrote:
> On Sun, Oct 22, 2017 at 11:46:41AM +0900, Stafford Horne wrote:
> > Add devicetree binding documentation for the OpenRISC platform
> > opencores,or1ksim.  This is the main OpenRISC reference platform
> > supporting multiple FPGA SoC's.
> > 
> > This format is based on some of the mips binding docs as we have
> > similar requirements.
> > 
> > Also, update maintainers so openrisc related binding changes are visible
> > to the openrisc team.
> 
> Your subject is wrong because this is not a dts patch. Use 
> "dt-bindings: openrisc: ..."

I will fix that,  I should have noticed.

> > 
> > Suggested-by: Pavel Machek <pavel@ucw.cz>
> > Signed-off-by: Stafford Horne <shorne@gmail.com>
> > ---
> >  .../bindings/openrisc/opencores/or1ksim.txt        | 39 ++++++++++++++++++++++
> >  MAINTAINERS                                        |  1 +
> >  2 files changed, 40 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt
> 
> Otherwise,
> 
> Acked-by: Rob Herring <robh@kernel.org>

Thank you.

[OpenRISC] [PATCH 3/3] openrisc: dts: Add OpenRISC platform SoC

[Stafford Horne]

On Sun, Oct 22, 2017 at 11:46:41AM +0900, Stafford Horne wrote:
> Add devicetree binding documentation for the OpenRISC platform
> opencores,or1ksim.  This is the main OpenRISC reference platform
> supporting multiple FPGA SoC's.
> 
> This format is based on some of the mips binding docs as we have
> similar requirements.
> 
> Also, update maintainers so openrisc related binding changes are visible
> to the openrisc team.
> 

[..]

> diff --git a/MAINTAINERS b/MAINTAINERS
> index a57d13cb414d..71e4f6762196 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -10008,6 +10008,7 @@ T:	git git://github.com/openrisc/linux.git
>  L:	openrisc at lists.librecores.org
>  W:	http://openrisc.io
>  S:	Maintained
> +F;	Documentation/devicetree/bindings/openrisc/

FYI, I found this typo (; vs :) which I have fixed and am pushing to next.

>  F:	Documentation/openrisc/
>  F:	arch/openrisc/
>  F:	drivers/irqchip/irq-or1k-*
> -- 
> 2.13.6
>