Re: [PATCH 2/9] PCI: host: brcmstb: add DT docs for Brcmstb PCIe device

[Jim Quinlan]

On Wed, Oct 11, 2017 at 8:55 PM, Brian Norris
<computersforpeace@xxxxxxxxx> wrote:
> Hi Jim,
>
> On Wed, Oct 11, 2017 at 06:34:22PM -0400, Jim Quinlan wrote:

pcie->gen = 0;

>> The DT bindings description of the Brcmstb PCIe device is described.  This
>> node can be used by almost all Broadcom settop box chips, using
>> ARM, ARM64, or MIPS CPU architectures.
>>
>> Signed-off-by: Jim Quinlan <jim2101024@xxxxxxxxx>
>> ---
>>  .../devicetree/bindings/pci/brcmstb-pci.txt        | 106 +++++++++++++++++++++
>>  1 file changed, 106 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/pci/brcmstb-pci.txt
>>
>> diff --git a/Documentation/devicetree/bindings/pci/brcmstb-pci.txt b/Documentation/devicetree/bindings/pci/brcmstb-pci.txt
>> new file mode 100644
>> index 0000000..2f699da
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/pci/brcmstb-pci.txt
>> @@ -0,0 +1,106 @@
>> +Brcmstb PCIe Host Controller Device Tree Bindings
>> +
>> +Introduction:
>> +  The brcmstb host controller closely follows the example set in
>> +
>> +     [1] http://devicetree.org/Device_Tree_Usage#PCI_Host_Bridge
>> +
>> +  The rest of this document explains some added customizations and
>> +  offers an example Brcmstb PCIe host controller DT node.
>> +
>> +Required Properties:
>> +  reg -- the register start address and length for the PCIe block.
>> +      Additional start,length pairs may be specified for clock addresses.
>> +  interrupts -- two interrupts are specified; the first interrupt is for
>> +      the PCI host controller and the second is for MSI if the built-in
>> +      MSI controller is to be used.
>> +  interrupt-names -- names of the interrupts (above): "pcie" and "msi".
>> +  compatible -- must be one of: "brcm,bcm7425-pcie", "brcm,bcm7435-pcie",
>> +      or "brcm,bcm7278-pcie".
>> +  #address-cells -- the number of address cells for PCI-space.
>> +  #size-cells -- the number of size cells for PCI-space.
>> +  ranges -- See [1]; a specification of the outbound windows for the host
>> +      controller.  Each outbound window is described by a n-tuple:
>> +          (3 cells) -- PCIe space start address; one cell for attributes
>> +                       and two cells for the 64-bit PCIe address.
>> +          (x cells) -- CPU/System start address, number of cells is determined
>> +                       by the parent node's #address-cells.
>> +          (y cells) -- Size of region, number of cells determined by the
>> +                       parent node's #size-cells.
>> +      Due to hardware limitations, there may be a maximum of four
>> +      non-contiguous ranges specified.
>> +  #interrupt-cells -- number of cells used to describe the interrupt.
>> +  interrupt-map-mask -- see [1]; four cells, the first three are zero
>> +      for our uses and the fourth cell is the mask (val = 0x7) for
>> +      the legacy interrupt number [1..4].
>> +  interrupt-map -- See [1]; there are four interrupts (INTA, INTB,
>> +      INTC, and INTD) to be mapped; each interrupt requires 5 cells
>> +      plus the size of the interrupt specifier.
>> +  linux,pci-domain -- the domain of the host controller.
>> +
>> +Optional Properties:
>> +  clocks -- list of clock phandles.  If specified, this should list one
>> +      clock.
>> +  clock-names -- the "local" names of the clocks specified in 'clocks'.  Note
>> +      that if the 'clocks' property is given, 'clock-names' is mandatory,
>> +      and the name of the clock is expected to be "sw_pcie".
>> +  dma-ranges -- Similar in structure to ranges, each dma region is
>> +      specified with a n-tuple.  Dma-regions describe the inbound
>> +      accesses from EP to RC; it translates the pci address that the
>> +      EP "sees" to the CPU address in memory.  This property is needed
>> +      because the design of the Brcmstb memory subsystem often precludes
>> +      idenity-mapping between CPU address space and PCIe address space.
>> +      Each range is described by a n-tuple:
>> +          (3 cells) -- PCIe space start address; one cell for attributes
>> +                       and two cells for the 64-bit PCIe address.
>> +          (x cells) -- CPU/System start address, number of cells is determined
>> +                       by the parent node's #address-cells.
>> +          (y cells) -- Size of region, number of cells determined by the
>> +                       parent node's #size-cells.
>> +  msi-parent -- if MSI is to be used, this must be a phandle to the
>> +      msi-parent.  If this prop is set to the phandle of the PCIe
>> +      node, or if the msi-parent prop is missing, the PCIE controller
>> +      will attempt to use its built in MSI controller.
>> +  msi-controller -- this property should only be specified if the
>> +      PCIe controller is using its internal MSI controller.
>> +  brcm,ssc -- (boolean) indicates usage of spread-spectrum clocking.
>> +  brcm,gen --  (integer) indicates desired generation of link:
>> +      1 => 2.5 Gbps, 2 => 5.0 Gbps, 3 => 8.0 Gbps.
>
> Does this differ from the 'max-link-speed' now documented in
> Documentation/devicetree/bindings/pci/pci.txt? If not, might as well use
> it, and of_pci_get_max_link_speed().
>
Hi Brian, yes that's what it is, will fix.

>> +  supply-names -- the names of voltage regulators that the root
>> +      complex should turn off/on/on on suspend/resume/boot.  This
>> +      is a string list.
>> +  supplies -- A collection of phandles to a regulator nodes, see
>> +      Documentation/devicetree/bindings/regulator/ for specific
>> +      bindings. The number and order of phandles must match
>> +      exactly the number of strings in the "supply-names" property.
>> +
>> +Example Node:
>> +
>> +pcie0:       pcie@f0460000 {
>
> ^^ You've got a tab after the colon. Makes this look funky in my
> vim/mutt :)
>
> Brian
>
Will fix.

>> +             reg = <0x0 0xf0460000 0x0 0x9310>;
>> +             interrupts = <0x0 0x0 0x4>;
>> +             compatible = "brcm,pci-plat-dev";
>> +             #address-cells = <3>;
>> +             #size-cells = <2>;
>> +             ranges = <0x02000000 0x00000000 0x00000000 0x00000000 0xc0000000 0x00000000 0x08000000
>> +                       0x02000000 0x00000000 0x08000000 0x00000000 0xc8000000 0x00000000 0x08000000>;
>> +             #interrupt-cells = <1>;
>> +             interrupt-map-mask = <0 0 0 7>;
>> +             interrupt-map = <0 0 0 1 &intc 0 47 3
>> +                              0 0 0 2 &intc 0 48 3
>> +                              0 0 0 3 &intc 0 49 3
>> +                              0 0 0 4 &intc 0 50 3>;
>> +             interrupt-names = "pcie_0_inta",
>> +                               "pcie_0_intb",
>> +                               "pcie_0_intc",
>> +                               "pcie_0_intd";
>> +             clocks = <&sw_pcie0>;
>> +             clock-names = "sw_pcie";
>> +             msi-parent = <&pcie0>;  /* use PCIe's internal MSI controller */
>> +             msi-controller;         /* use PCIe's internal MSI controller */
>> +             brcm,ssc;
>> +             brcm,gen = <1>;
>> +             supply-names = "vreg-wifi-pwr";
>> +             supplies = <&vreg-wifi-pwr>;
>> +             linux,pci-domain = <0>;
>> +     };
>> --
>> 1.9.0.138.g2de3478
>>