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

# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/bus/qcom,ebi2.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Qualcomm External Bus Interface 2 (EBI2)

description: |
  The EBI2 contains two peripheral blocks: XMEM and LCDC. The XMEM handles any
  external memory (such as NAND or other memory-mapped peripherals) whereas
  LCDC handles LCD displays.

  As it says it connects devices to an external bus interface, meaning address
  lines (up to 9 address lines so can only address 1KiB external memory space),
  data lines (16 bits), OE (output enable), ADV (address valid, used on some
  NOR flash memories), WE (write enable). This on top of 6 different chip selects
  (CS0 thru CS5) so that in theory 6 different devices can be connected.

  Apparently this bus is clocked at 64MHz. It has dedicated pins on the package
  and the bus can only come out on these pins, however if some of the pins are
  unused they can be left unconnected or remuxed to be used as GPIO or in some
  cases other orthogonal functions as well.

  Also CS1 and CS2 has -A and -B signals. Why they have that is unclear to me.

  The chip selects have the following memory range assignments. This region of
  memory is referred to as "Chip Peripheral SS FPB0" and is 168MB big.

  Chip Select                     Physical address base
  CS0 GPIO134                     0x1a800000-0x1b000000 (8MB)
  CS1 GPIO39 (A) / GPIO123 (B)    0x1b000000-0x1b800000 (8MB)
  CS2 GPIO40 (A) / GPIO124 (B)    0x1b800000-0x1c000000 (8MB)
  CS3 GPIO133                     0x1d000000-0x25000000 (128 MB)
  CS4 GPIO132                     0x1c800000-0x1d000000 (8MB)
  CS5 GPIO131                     0x1c000000-0x1c800000 (8MB)

  The APQ8060 Qualcomm Application Processor User Guide, 80-N7150-14 Rev. A,
  August 6, 2012 contains some incomplete documentation of the EBI2.

  FIXME: the manual mentions "write precharge cycles" and "precharge cycles".
  We have not been able to figure out which bit fields these correspond to
  in the hardware, or what valid values exist. The current hypothesis is that
  this is something just used on the FAST chip selects and that the SLOW
  chip selects are understood fully. There is also a "byte device enable"
  flag somewhere for 8bit memories.

  FIXME: The chipselects have SLOW and FAST configuration registers. It's a bit
  unclear what this means, if they are mutually exclusive or can be used
  together, or if some chip selects are hardwired to be FAST and others are SLOW
  by design.

  The XMEM registers are totally undocumented but could be partially decoded
  because the Cypress AN49576 Antioch Westbridge apparently has suspiciously
  similar register layout, see: http://www.cypress.com/file/105771/download

maintainers:
  - Bjorn Andersson <andersson@kernel.org>

properties:
  compatible:
    enum:
      - qcom,apq8060-ebi2
      - qcom,msm8660-ebi2

  reg:
    items:
      - description: EBI2 config region
      - description: XMEM config region

  reg-names:
    items:
      - const: ebi2
      - const: xmem

  ranges: true

  clocks:
    items:
      - description: EBI_2X clock
      - description: EBI clock

  clock-names:
    items:
      - const: ebi2x
      - const: ebi2

  '#address-cells':
    const: 2

  '#size-cells':
    const: 1

required:
  - compatible
  - reg
  - reg-names
  - ranges
  - clocks
  - clock-names
  - '#address-cells'
  - '#size-cells'

patternProperties:
  "^.*@[0-5],[0-9a-f]+$":
    type: object
    additionalProperties: true
    properties:
      reg:
        maxItems: 1

      # SLOW chip selects
      qcom,xmem-recovery-cycles:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          The time the memory continues to drive the data bus after OE
          is de-asserted, in order to avoid contention on the data bus.
          They are inserted when reading one CS and switching to another
          CS or read followed by write on the same CS. Minimum value is
          actually 1, so a value of 0 will still yield 1 recovery cycle.
        minimum: 0
        maximum: 15

      qcom,xmem-write-hold-cycles:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          The extra cycles inserted after every write minimum 1. The
          data out is driven from the time WE is asserted until CS is
          asserted. With a hold of 1 (value = 0), the CS stays active
          for 1 extra cycle, etc.
        minimum: 0
        maximum: 15

      qcom,xmem-write-delta-cycles:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          The initial latency for write cycles inserted for the first
          write to a page or burst memory.
        minimum: 0
        maximum: 255

      qcom,xmem-read-delta-cycles:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          The initial latency for read cycles inserted for the first
          read to a page or burst memory.
        minimum: 0
        maximum: 255

      qcom,xmem-write-wait-cycles:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          The number of wait cycles for every write access.
        minimum: 0
        maximum: 15

      qcom,xmem-read-wait-cycles:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          The number of wait cycles for every read access.
        minimum: 0
        maximum: 15


      # FAST chip selects
      qcom,xmem-address-hold-enable:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          Holds the address for an extra cycle to meet hold time
          requirements with ADV assertion, when set to 1.
        enum: [ 0, 1 ]

      qcom,xmem-adv-to-oe-recovery-cycles:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          The number of cycles elapsed before an OE assertion, with
          respect to the cycle where ADV (address valid) is asserted.
        minimum: 0
        maximum: 3

      qcom,xmem-read-hold-cycles:
        $ref: /schemas/types.yaml#/definitions/uint32
        description: >
          The length in cycles of the first segment of a read transfer.
          For a single read transfer this will be the time from CS
          assertion to OE assertion.
        minimum: 0
        maximum: 15

    required:
      - reg

additionalProperties: false

examples:
  - |
    #include <dt-bindings/clock/qcom,gcc-msm8660.h>
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/gpio/gpio.h>

    external-bus@1a100000 {
        compatible = "qcom,msm8660-ebi2";
        reg = <0x1a100000 0x1000>, <0x1a110000 0x1000>;
        reg-names = "ebi2", "xmem";
        ranges = <0 0x0 0x1a800000 0x00800000>,
                 <1 0x0 0x1b000000 0x00800000>,
                 <2 0x0 0x1b800000 0x00800000>,
                 <3 0x0 0x1d000000 0x08000000>,
                 <4 0x0 0x1c800000 0x00800000>,
                 <5 0x0 0x1c000000 0x00800000>;

        clocks = <&gcc EBI2_2X_CLK>, <&gcc EBI2_CLK>;
        clock-names = "ebi2x", "ebi2";

        #address-cells = <2>;
        #size-cells = <1>;

        ethernet@2,0 {
            compatible = "smsc,lan9221", "smsc,lan9115";
            reg = <2 0x0 0x100>;

            interrupts-extended = <&pm8058_gpio 7 IRQ_TYPE_EDGE_FALLING>,
                                  <&tlmm 29 IRQ_TYPE_EDGE_RISING>;
            reset-gpios = <&tlmm 30 GPIO_ACTIVE_LOW>;

            phy-mode = "mii";
            reg-io-width = <2>;
            smsc,force-external-phy;
            smsc,irq-push-pull;

            /* SLOW chipselect config */
            qcom,xmem-recovery-cycles = <0>;
            qcom,xmem-write-hold-cycles = <3>;
            qcom,xmem-write-delta-cycles = <31>;
            qcom,xmem-read-delta-cycles = <28>;
            qcom,xmem-write-wait-cycles = <9>;
            qcom,xmem-read-wait-cycles = <9>;
        };
    };