OpenRISC doc updates

PATCH In review Stafford Horne 2 participants 7 messages Oct 22, 2017 – Nov 3, 2017

Subsystems (3)

Device tree bindings Documentation Openrisc architecture

lore

Share & tools

lore

Stafford Horne

author maintainer

2017-10-22 02:46 UTC #0 lore raw

cover OpenRISC doc updates

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%)

Signature · 1 line

2.13.6

Stafford Horne

author maintainer

2017-10-22 02:46 UTC #1 lore raw

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

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 <[email protected]>

---
 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%)

Documentation/openrisc/README renamed from arch/openrisc/README.openrisc +0 -0

similarity index 100%
rename from arch/openrisc/README.openrisc
rename to Documentation/openrisc/README

Documentation/openrisc/TODO renamed from arch/openrisc/TODO.openrisc +0 -0

similarity index 100%
rename from arch/openrisc/TODO.openrisc
rename to Documentation/openrisc/TODO

MAINTAINERS +1 -0

index 8ce029872089..a57d13cb414d 100644
@@ -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-*

Signature · 1 line

2.13.6

Stafford Horne

author maintainer

2017-10-22 02:46 UTC #2 lore raw

PATCH 2/3 Documentation: openrisc: Updates to README

In reply to 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

Signed-off-by Stafford Horne <[email protected]>

---
 Documentation/openrisc/README | 65 +++++++++++++++++++++++++------------------
 1 file changed, 38 insertions(+), 27 deletions(-)

Documentation/openrisc/README +38 ~~-27~~

index 072069ab5100..777a893d533d 100644
@@ -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
 
 ---------------------------------------------------------------------

Signature · 1 line

2.13.6

Stafford Horne

author maintainer

2017-10-22 02:46 UTC #3 lore raw

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

In reply to 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.

Signed-off-by Stafford Horne <[email protected]>

---
 .../bindings/openrisc/opencores/or1ksim.txt        | 39 ++++++++++++++++++++++
 MAINTAINERS                                        |  1 +
 2 files changed, 40 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt

Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt new file +39 -0

new file mode 100644
index 000000000000..4950c794ecbb
@@ -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@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.

MAINTAINERS +1 -0

index a57d13cb414d..71e4f6762196 100644
@@ -10008,6 +10008,7 @@ T:	git git://github.com/openrisc/linux.git
 L:	[email protected]
 W:	http://openrisc.io
 S:	Maintained
+F;	Documentation/devicetree/bindings/openrisc/
 F:	Documentation/openrisc/
 F:	arch/openrisc/
 F:	drivers/irqchip/irq-or1k-*

Signature · 1 line

2.13.6

Rob Herring

maintainer Acked-by on v1 3/3

2017-10-27 03:18 UTC #4 lore raw

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

Quoted 9 lines · 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.

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

Quoted 8 lines

Signed-off-by Stafford Horne <[email protected]>

---
 .../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 <[email protected]>

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Stafford Horne

author maintainer

2017-10-29 11:33 UTC #5 lore raw

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

Quoted 5 lines · Rob Herring

Quoted 4 lines · Stafford Horne
Add devicetree binding documentation for the OpenRISC platform opencores,or1ksim. This is the main OpenRISC reference platform supporting multiple FPGA SoC's.

Quoted 8 lines

Quoted 5 lines
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.

Quoted 9 lines

Quoted 8 lines

Signed-off-by Stafford Horne <[email protected]>

---
 .../bindings/openrisc/opencores/or1ksim.txt        | 39 ++++++++++++++++++++++
 MAINTAINERS                                        |  1 +
 2 files changed, 40 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt

Quoted 3 lines

Otherwise,
Acked-by Rob Herring <[email protected]>

Thank you.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Stafford Horne

author maintainer

2017-11-03 05:04 UTC #6 lore raw

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

In reply to Stafford Horne

Quoted 10 lines · 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.

[..]

MAINTAINERS T: git git://github.com/openrisc/linux.git · line 10011

Quoted 9 lines

MAINTAINERS +1 -0

index a57d13cb414d..71e4f6762196 100644
@@ -10008,6 +10008,7 @@ T:	git git://github.com/openrisc/linux.git
 L:	[email protected]
 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.

Quoted 6 lines

MAINTAINERS +0 -0

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

Signature · 1 line

2.13.6

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html