Documentation/devicetree/bindings/bus/qcom,ebi2.yaml

   1 # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/bus/qcom,ebi2.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: Qualcomm External Bus Interface 2 (EBI2)
   8
   9 description: |
  10   The EBI2 contains two peripheral blocks: XMEM and LCDC. The XMEM handles any
  11   external memory (such as NAND or other memory-mapped peripherals) whereas
  12   LCDC handles LCD displays.
  13
  14   As it says it connects devices to an external bus interface, meaning address
  15   lines (up to 9 address lines so can only address 1KiB external memory space),
  16   data lines (16 bits), OE (output enable), ADV (address valid, used on some
  17   NOR flash memories), WE (write enable). This on top of 6 different chip selects
  18   (CS0 thru CS5) so that in theory 6 different devices can be connected.
  19
  20   Apparently this bus is clocked at 64MHz. It has dedicated pins on the package
  21   and the bus can only come out on these pins, however if some of the pins are
  22   unused they can be left unconnected or remuxed to be used as GPIO or in some
  23   cases other orthogonal functions as well.
  24
  25   Also CS1 and CS2 has -A and -B signals. Why they have that is unclear to me.
  26
  27   The chip selects have the following memory range assignments. This region of
  28   memory is referred to as "Chip Peripheral SS FPB0" and is 168MB big.
  29
  30   Chip Select                     Physical address base
  31   CS0 GPIO134                     0x1a800000-0x1b000000 (8MB)
  32   CS1 GPIO39 (A) / GPIO123 (B)    0x1b000000-0x1b800000 (8MB)
  33   CS2 GPIO40 (A) / GPIO124 (B)    0x1b800000-0x1c000000 (8MB)
  34   CS3 GPIO133                     0x1d000000-0x25000000 (128 MB)
  35   CS4 GPIO132                     0x1c800000-0x1d000000 (8MB)
  36   CS5 GPIO131                     0x1c000000-0x1c800000 (8MB)
  37
  38   The APQ8060 Qualcomm Application Processor User Guide, 80-N7150-14 Rev. A,
  39   August 6, 2012 contains some incomplete documentation of the EBI2.
  40
  41   FIXME: the manual mentions "write precharge cycles" and "precharge cycles".
  42   We have not been able to figure out which bit fields these correspond to
  43   in the hardware, or what valid values exist. The current hypothesis is that
  44   this is something just used on the FAST chip selects and that the SLOW
  45   chip selects are understood fully. There is also a "byte device enable"
  46   flag somewhere for 8bit memories.
  47
  48   FIXME: The chipselects have SLOW and FAST configuration registers. It's a bit
  49   unclear what this means, if they are mutually exclusive or can be used
  50   together, or if some chip selects are hardwired to be FAST and others are SLOW
  51   by design.
  52
  53   The XMEM registers are totally undocumented but could be partially decoded
  54   because the Cypress AN49576 Antioch Westbridge apparently has suspiciously
  55   similar register layout, see: http://www.cypress.com/file/105771/download
  56
  57 maintainers:
  58   - Bjorn Andersson <andersson@kernel.org>
  59
  60 properties:
  61   compatible:
  62     enum:
  63       - qcom,apq8060-ebi2
  64       - qcom,msm8660-ebi2
  65
  66   reg:
  67     items:
  68       - description: EBI2 config region
  69       - description: XMEM config region
  70
  71   reg-names:
  72     items:
  73       - const: ebi2
  74       - const: xmem
  75
  76   ranges: true
  77
  78   clocks:
  79     items:
  80       - description: EBI_2X clock
  81       - description: EBI clock
  82
  83   clock-names:
  84     items:
  85       - const: ebi2x
  86       - const: ebi2
  87
  88   '#address-cells':
  89     const: 2
  90
  91   '#size-cells':
  92     const: 1
  93
  94 required:
  95   - compatible
  96   - reg
  97   - reg-names
  98   - ranges
  99   - clocks
 100   - clock-names
 101   - '#address-cells'
 102   - '#size-cells'
 103
 104 patternProperties:
 105   "^.*@[0-5],[0-9a-f]+$":
 106     type: object
 107     additionalProperties: true
 108     properties:
 109       reg:
 110         maxItems: 1
 111
 112       # SLOW chip selects
 113       qcom,xmem-recovery-cycles:
 114         $ref: /schemas/types.yaml#/definitions/uint32
 115         description: >
 116           The time the memory continues to drive the data bus after OE
 117           is de-asserted, in order to avoid contention on the data bus.
 118           They are inserted when reading one CS and switching to another
 119           CS or read followed by write on the same CS. Minimum value is
 120           actually 1, so a value of 0 will still yield 1 recovery cycle.
 121         minimum: 0
 122         maximum: 15
 123
 124       qcom,xmem-write-hold-cycles:
 125         $ref: /schemas/types.yaml#/definitions/uint32
 126         description: >
 127           The extra cycles inserted after every write minimum 1. The
 128           data out is driven from the time WE is asserted until CS is
 129           asserted. With a hold of 1 (value = 0), the CS stays active
 130           for 1 extra cycle, etc.
 131         minimum: 0
 132         maximum: 15
 133
 134       qcom,xmem-write-delta-cycles:
 135         $ref: /schemas/types.yaml#/definitions/uint32
 136         description: >
 137           The initial latency for write cycles inserted for the first
 138           write to a page or burst memory.
 139         minimum: 0
 140         maximum: 255
 141
 142       qcom,xmem-read-delta-cycles:
 143         $ref: /schemas/types.yaml#/definitions/uint32
 144         description: >
 145           The initial latency for read cycles inserted for the first
 146           read to a page or burst memory.
 147         minimum: 0
 148         maximum: 255
 149
 150       qcom,xmem-write-wait-cycles:
 151         $ref: /schemas/types.yaml#/definitions/uint32
 152         description: >
 153           The number of wait cycles for every write access.
 154         minimum: 0
 155         maximum: 15
 156
 157       qcom,xmem-read-wait-cycles:
 158         $ref: /schemas/types.yaml#/definitions/uint32
 159         description: >
 160           The number of wait cycles for every read access.
 161         minimum: 0
 162         maximum: 15
 163
 164
 165       # FAST chip selects
 166       qcom,xmem-address-hold-enable:
 167         $ref: /schemas/types.yaml#/definitions/uint32
 168         description: >
 169           Holds the address for an extra cycle to meet hold time
 170           requirements with ADV assertion, when set to 1.
 171         enum: [ 0, 1 ]
 172
 173       qcom,xmem-adv-to-oe-recovery-cycles:
 174         $ref: /schemas/types.yaml#/definitions/uint32
 175         description: >
 176           The number of cycles elapsed before an OE assertion, with
 177           respect to the cycle where ADV (address valid) is asserted.
 178         minimum: 0
 179         maximum: 3
 180
 181       qcom,xmem-read-hold-cycles:
 182         $ref: /schemas/types.yaml#/definitions/uint32
 183         description: >
 184           The length in cycles of the first segment of a read transfer.
 185           For a single read transfer this will be the time from CS
 186           assertion to OE assertion.
 187         minimum: 0
 188         maximum: 15
 189
 190     required:
 191       - reg
 192
 193 additionalProperties: false
 194
 195 examples:
 196   - |
 197     #include <dt-bindings/clock/qcom,gcc-msm8660.h>
 198     #include <dt-bindings/interrupt-controller/irq.h>
 199     #include <dt-bindings/gpio/gpio.h>
 200
 201     external-bus@1a100000 {
 202         compatible = "qcom,msm8660-ebi2";
 203         reg = <0x1a100000 0x1000>, <0x1a110000 0x1000>;
 204         reg-names = "ebi2", "xmem";
 205         ranges = <0 0x0 0x1a800000 0x00800000>,
 206                  <1 0x0 0x1b000000 0x00800000>,
 207                  <2 0x0 0x1b800000 0x00800000>,
 208                  <3 0x0 0x1d000000 0x08000000>,
 209                  <4 0x0 0x1c800000 0x00800000>,
 210                  <5 0x0 0x1c000000 0x00800000>;
 211
 212         clocks = <&gcc EBI2_2X_CLK>, <&gcc EBI2_CLK>;
 213         clock-names = "ebi2x", "ebi2";
 214
 215         #address-cells = <2>;
 216         #size-cells = <1>;
 217
 218         ethernet@2,0 {
 219             compatible = "smsc,lan9221", "smsc,lan9115";
 220             reg = <2 0x0 0x100>;
 221
 222             interrupts-extended = <&pm8058_gpio 7 IRQ_TYPE_EDGE_FALLING>,
 223                                   <&tlmm 29 IRQ_TYPE_EDGE_RISING>;
 224             reset-gpios = <&tlmm 30 GPIO_ACTIVE_LOW>;
 225
 226             phy-mode = "mii";
 227             reg-io-width = <2>;
 228             smsc,force-external-phy;
 229             smsc,irq-push-pull;
 230
 231             /* SLOW chipselect config */
 232             qcom,xmem-recovery-cycles = <0>;
 233             qcom,xmem-write-hold-cycles = <3>;
 234             qcom,xmem-write-delta-cycles = <31>;
 235             qcom,xmem-read-delta-cycles = <28>;
 236             qcom,xmem-write-wait-cycles = <9>;
 237             qcom,xmem-read-wait-cycles = <9>;
 238         };
 239     };