spi-controller.yaml

   1 # SPDX-License-Identifier: GPL-2.0
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/spi/spi-controller.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: SPI Controller Common Properties
   8
   9 maintainers:
  10   - Mark Brown <broonie@kernel.org>
  11
  12 description: |
  13   SPI busses can be described with a node for the SPI controller device
  14   and a set of child nodes for each SPI slave on the bus. The system SPI
  15   controller may be described for use in SPI master mode or in SPI slave mode,
  16   but not for both at the same time.
  17
  18 properties:
  19   $nodename:
  20     pattern: "^spi(@.*|-([0-9]|[1-9][0-9]+))?$"
  21
  22   "#address-cells":
  23     enum: [0, 1]
  24
  25   "#size-cells":
  26     const: 0
  27
  28   cs-gpios:
  29     description: |
  30       GPIOs used as chip selects.
  31       If that property is used, the number of chip selects will be
  32       increased automatically with max(cs-gpios, hardware chip selects).
  33
  34       So if, for example, the controller has 4 CS lines, and the
  35       cs-gpios looks like this
  36         cs-gpios = <&gpio1 0 0>, <0>, <&gpio1 1 0>, <&gpio1 2 0>;
  37
  38       Then it should be configured so that num_chipselect = 4, with
  39       the following mapping
  40         cs0 : &gpio1 0 0
  41         cs1 : native
  42         cs2 : &gpio1 1 0
  43         cs3 : &gpio1 2 0
  44
  45       The second flag of a gpio descriptor can be GPIO_ACTIVE_HIGH (0)
  46       or GPIO_ACTIVE_LOW(1). Legacy device trees often use 0.
  47
  48       There is a special rule set for combining the second flag of an
  49       cs-gpio with the optional spi-cs-high flag for SPI slaves.
  50
  51       Each table entry defines how the CS pin is to be physically
  52       driven (not considering potential gpio inversions by pinmux):
  53
  54       device node     | cs-gpio       | CS pin state active | Note
  55       ================+===============+=====================+=====
  56       spi-cs-high     | -             | H                   |
  57       -               | -             | L                   |
  58       spi-cs-high     | ACTIVE_HIGH   | H                   |
  59       -               | ACTIVE_HIGH   | L                   | 1
  60       spi-cs-high     | ACTIVE_LOW    | H                   | 2
  61       -               | ACTIVE_LOW    | L                   |
  62
  63       Notes:
  64       1) Should print a warning about polarity inversion.
  65          Here it would be wise to avoid and define the gpio as
  66          ACTIVE_LOW.
  67       2) Should print a warning about polarity inversion
  68          because ACTIVE_LOW is overridden by spi-cs-high.
  69          Should be generally avoided and be replaced by
  70          spi-cs-high + ACTIVE_HIGH.
  71
  72   num-cs:
  73     $ref: /schemas/types.yaml#/definitions/uint32
  74     description:
  75       Total number of chip selects.
  76
  77   spi-slave:
  78     $ref: /schemas/types.yaml#/definitions/flag
  79     description:
  80       The SPI controller acts as a slave, instead of a master.
  81
  82   slave:
  83     type: object
  84
  85     properties:
  86       compatible:
  87         description:
  88           Compatible of the SPI device.
  89
  90     required:
  91       - compatible
  92
  93 patternProperties:
  94   "^.*@[0-9a-f]+$":
  95     type: object
  96     $ref: spi-peripheral-props.yaml
  97     additionalProperties: true
  98
  99     properties:
 100       spi-3wire:
 101         $ref: /schemas/types.yaml#/definitions/flag
 102         description:
 103           The device requires 3-wire mode.
 104
 105       spi-cpha:
 106         $ref: /schemas/types.yaml#/definitions/flag
 107         description:
 108           The device requires shifted clock phase (CPHA) mode.
 109
 110       spi-cpol:
 111         $ref: /schemas/types.yaml#/definitions/flag
 112         description:
 113           The device requires inverse clock polarity (CPOL) mode.
 114
 115     required:
 116       - compatible
 117       - reg
 118
 119 allOf:
 120   - if:
 121       not:
 122         required:
 123           - spi-slave
 124     then:
 125       properties:
 126         "#address-cells":
 127           const: 1
 128     else:
 129       properties:
 130         "#address-cells":
 131           const: 0
 132
 133 additionalProperties: true
 134
 135 examples:
 136   - |
 137     spi@80010000 {
 138         #address-cells = <1>;
 139         #size-cells = <0>;
 140         compatible = "fsl,imx28-spi";
 141         reg = <0x80010000 0x2000>;
 142         interrupts = <96>;
 143         dmas = <&dma_apbh 0>;
 144         dma-names = "rx-tx";
 145
 146         display@0 {
 147             compatible = "lg,lg4573";
 148             spi-max-frequency = <1000000>;
 149             reg = <0>;
 150         };
 151
 152         sensor@1 {
 153             compatible = "bosch,bme680";
 154             spi-max-frequency = <100000>;
 155             reg = <1>;
 156         };
 157
 158         flash@2 {
 159             compatible = "jedec,spi-nor";
 160             spi-max-frequency = <50000000>;
 161             reg = <2>, <3>;
 162             stacked-memories = /bits/ 64 <0x10000000 0x10000000>;
 163         };
 164     };