Re: [PATCH v2 2/3] ARM: dts: socfpga: fpga bridges bindings docs

[Pantelis Antoniou]

Hi Alan,

> On Oct 24, 2014, at 02:51 , atull@xxxxxxxxxxxxxxxxxxxxx wrote:
> 
> From: Alan Tull <atull@xxxxxxxxxxxxxxxxxxxxx>
> 
> Add DTS binding documentation for the Altera FPGA bridges.
> 
> Signed-off-by: Alan Tull <atull@xxxxxxxxxxxxxxxxxxxxx>
> ---
> .../bindings/fpga/altera-fpga2sdram-bridge.txt     |   57 ++++++++++++++++++++
> .../bindings/fpga/altera-hps2fpga-bridge.txt       |   53 ++++++++++++++++++
> 2 files changed, 110 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
> create mode 100644 Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
> 
> diff --git a/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
> new file mode 100644
> index 0000000..cc8f522
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
> @@ -0,0 +1,57 @@
> +Altera FPGA To SDRAM Bridge Driver
> +
> +This driver manages a bridge between an FPGA and the SDRAM used by an host
> +processor system (HPS). The bridge contains a number read ports, write ports,
> +and command ports.  Reconfiguring these ports requires that no SDRAM
> +transactions occur during reconfiguration.  In other words, the code
> +reconfiguring the ports cannot be run out of SDRAM nor can the FPGA access the
> +SDRAM during the reconfiguration.  This driver does not support reconfiguring
> +the ports.  Typcially, the ports are configured by code running out of onchip
> +ram before Linux is started.
> +
> +This driver supports enabling and disabling of the configured ports all at
> +once, which allows for safe reprogramming of the FPGA from user space, provided
> +the new FPGA image uses the same port configuration. User space can enable or
> +disable the bridge by writing a "1" or a "0", respectively, to its enable file
> +under bridge's entry in /sys/class/fpga-bridge. Typically, one disables the
> +bridges before reprogramming the FPGA.  Once the FPGA is reprogrammed, the
> +bridges are reenabled.
> +
> +Required properties:
> +
> + - compatible       : "altr,socfpga-fpga2sdram-bridge"
> +
> + - read-ports-mask  : Bits 0 to 3 corresponds read ports 0 to 3. A bit set to 1
> +                      indicates the corresponding read port should be enabled.
> +
> + - write-ports-mask : Bits 0 to 3 corresponds write ports 0 to 3. A bit set
> +                      to 1 indicates the corresponding write port should be
> +                      enabled.
> +
> + - cmd-ports-mask   : Bits 0 to 5 correspond to command ports 0 to 5. A bit set
> +                      to 1 indicates the corresponding command port should be
> +                      enabled.
> +
> + - altr,sdr-syscon  : phandle of the sdr module
> +
> +Optional properties:
> +
> + - label            : name that you want this bridge to show up as under
> +                      /sys/class/fpga-bridge. Default is br<device#> if this is
> +                      not specified.
> +
> + - init-val         : 0 if driver should disable bridge at startup
> +                      1 if driver should enable bridge at startup
> +                      driver leaves bridge in current state if property not
> +		      specified.

Isnât init-val a boolean property? Itâs not named very well.

Along with the label, is kinda hard to defend as configuration in DT.

We need to start thinking about configuration, so let me throw that in
and fan the Monday flames to a nice red-hot color.

/ {
	chosen {
		linux {
			fpga-bridge {
				node = <&FPGA_BRIDGE>;
				label = âfooâ;
				enable-bridge-on-startup;
			}
		};
	};
};

We will need accessors for drivers that iterate over the chosen/linux node children
and pick up the properties meant for the given driver node.

We also need to define behaviour in case those configuration properties are absent. 

Let the flames beginâ

> +
> +Example:
> +	fpga2sdram_br: fpgabridge@3 {
> +		compatible = "altr,socfpga-fpga2sdram-bridge";
> +		label = "fpga2sdram";
> +		altr,sdr-syscon = <&sdr>;
> +		read-ports-mask = <3>;
> +		write-ports-mask = <3>;
> +		cmd-ports-mask = <0xd>;
> +		init-val = <0>;
> +	};
> diff --git a/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
> new file mode 100644
> index 0000000..bc24a2e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
> @@ -0,0 +1,53 @@
> +Altera FPGA/HPS Bridge Driver
> +
> +This driver manages a bridge between a FPGA and a host processor system (HPS).
> +User space can enable or disable the bridge by writing a "1" or a "0",
> +respectively, to its enable file under bridge's entry in
> +/sys/class/fpga-bridge.  Typically, one disables the bridges before
> +reprogramming the FPGA.  Once the FPGA is reprogrammed, the bridges are
> +reenabled.
> +
> +Required properties:
> +
> + - compatible     : should contain one of:
> +                     "altr,socfpga-hps2fpga-bridge"
> +                     "altr,socfpga-lwhps2fpga-bridge"
> +                     "altr,socfpga-fpga2hps-bridge"
> +
> + - clocks         : clocks used by this module
> +
> + - altr,l3-syscon : phandle of the l3 interconnect module
> +
> +Optional properties:
> + - label          : name that you want this bridge to show up as under
> +                    /sys/class/fpga-bridge.  Default is br<device#> if this is
> +                    not specified.
> +
> + - init-val       : 0 if driver should disable bridge at startup
> +                    1 if driver should enable bridge at startup
> +                    driver leaves bridge in current state if property not
> +                    specified.
> +
> +Example:
> +	hps_fpgabridge0: fpgabridge@0 {
> +		compatible = "altr,socfpga-hps2fpga-bridge";
> +		label = "hps2fpga";
> +		altr,l3-syscon = <&l3regs>;
> +		clocks = <&l4_main_clk>;
> +		init-val = <1>;
> +	};
> +
> +	hps_fpgabridge1: fpgabridge@1 {
> +		compatible = "altr,socfpga-lwhps2fpga-bridge";
> +		label = "lwhps2fpga";
> +		altr,l3-syscon = <&l3regs>;
> +		clocks = <&l4_main_clk>;
> +		init-val = <0>;
> +	};
> +
> +	hps_fpgabridge2: fpgabridge@2 {
> +		compatible = "altr,socfpga-fpga2hps-bridge";
> +		label = "fpga2hps";
> +		altr,l3-syscon = <&l3regs>;
> +		clocks = <&l4_main_clk>;
> +	};
> -- 
> 1.7.9.5
> 

Regards

â Pantelis


--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/