Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml

   1 # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: "http://devicetree.org/schemas/bindings/iio/adc/st,stm32-adc.yaml#"
   5 $schema: "http://devicetree.org/meta-schemas/core.yaml#"
   6
   7 title: STMicroelectronics STM32 ADC bindings
   8
   9 description: |
  10   STM32 ADC is a successive approximation analog-to-digital converter.
  11   It has several multiplexed input channels. Conversions can be performed
  12   in single, continuous, scan or discontinuous mode. Result of the ADC is
  13   stored in a left-aligned or right-aligned 32-bit data register.
  14   Conversions can be launched in software or using hardware triggers.
  15
  16   The analog watchdog feature allows the application to detect if the input
  17   voltage goes beyond the user-defined, higher or lower thresholds.
  18
  19   Each STM32 ADC block can have up to 3 ADC instances.
  20
  21 maintainers:
  22   - Fabrice Gasnier <fabrice.gasnier@st.com>
  23
  24 properties:
  25   compatible:
  26     enum:
  27       - st,stm32f4-adc-core
  28       - st,stm32h7-adc-core
  29       - st,stm32mp1-adc-core
  30
  31   reg:
  32     maxItems: 1
  33
  34   interrupts:
  35     description: |
  36       One or more interrupts for ADC block, depending on part used:
  37         - stm32f4 and stm32h7 share a common ADC interrupt line.
  38         - stm32mp1 has two separate interrupt lines, one for each ADC within
  39           ADC block.
  40     minItems: 1
  41     maxItems: 2
  42
  43   clocks:
  44     description: |
  45       Core can use up to two clocks, depending on part used:
  46         - "adc" clock: for the analog circuitry, common to all ADCs.
  47           It's required on stm32f4.
  48           It's optional on stm32h7 and stm32mp1.
  49         - "bus" clock: for registers access, common to all ADCs.
  50           It's not present on stm32f4.
  51           It's required on stm32h7 and stm32mp1.
  52
  53   clock-names: true
  54
  55   st,max-clk-rate-hz:
  56     description:
  57       Allow to specify desired max clock rate used by analog circuitry.
  58
  59   vdda-supply:
  60     description: Phandle to the vdda input analog voltage.
  61
  62   vref-supply:
  63     description: Phandle to the vref input analog reference voltage.
  64
  65   booster-supply:
  66     description:
  67       Phandle to the embedded booster regulator that can be used to supply ADC
  68       analog input switches on stm32h7 and stm32mp1.
  69
  70   vdd-supply:
  71     description:
  72       Phandle to the vdd input voltage. It can be used to supply ADC analog
  73       input switches on stm32mp1.
  74
  75   st,syscfg:
  76     description:
  77       Phandle to system configuration controller. It can be used to control the
  78       analog circuitry on stm32mp1.
  79     allOf:
  80       - $ref: "/schemas/types.yaml#/definitions/phandle-array"
  81
  82   interrupt-controller: true
  83
  84   '#interrupt-cells':
  85     const: 1
  86
  87   '#address-cells':
  88     const: 1
  89
  90   '#size-cells':
  91     const: 0
  92
  93 allOf:
  94   - if:
  95       properties:
  96         compatible:
  97           contains:
  98             const: st,stm32f4-adc-core
  99
 100     then:
 101       properties:
 102         clocks:
 103           maxItems: 1
 104
 105         clock-names:
 106           const: adc
 107
 108         interrupts:
 109           items:
 110             - description: interrupt line common for all ADCs
 111
 112         st,max-clk-rate-hz:
 113           minimum: 600000
 114           maximum: 36000000
 115           default: 36000000
 116
 117         booster-supply: false
 118
 119         vdd-supply: false
 120
 121         st,syscfg: false
 122
 123   - if:
 124       properties:
 125         compatible:
 126           contains:
 127             const: st,stm32h7-adc-core
 128
 129     then:
 130       properties:
 131         clocks:
 132           minItems: 1
 133           maxItems: 2
 134
 135         clock-names:
 136           items:
 137             - const: bus
 138             - const: adc
 139           minItems: 1
 140           maxItems: 2
 141
 142         interrupts:
 143           items:
 144             - description: interrupt line common for all ADCs
 145
 146         st,max-clk-rate-hz:
 147           minimum: 120000
 148           maximum: 36000000
 149           default: 36000000
 150
 151         vdd-supply: false
 152
 153         st,syscfg: false
 154
 155   - if:
 156       properties:
 157         compatible:
 158           contains:
 159             const: st,stm32mp1-adc-core
 160
 161     then:
 162       properties:
 163         clocks:
 164           minItems: 1
 165           maxItems: 2
 166
 167         clock-names:
 168           items:
 169             - const: bus
 170             - const: adc
 171           minItems: 1
 172           maxItems: 2
 173
 174         interrupts:
 175           items:
 176             - description: interrupt line for ADC1
 177             - description: interrupt line for ADC2
 178
 179         st,max-clk-rate-hz:
 180           minimum: 120000
 181           maximum: 36000000
 182           default: 36000000
 183
 184 additionalProperties: false
 185
 186 required:
 187   - compatible
 188   - reg
 189   - interrupts
 190   - clocks
 191   - clock-names
 192   - vdda-supply
 193   - vref-supply
 194   - interrupt-controller
 195   - '#interrupt-cells'
 196   - '#address-cells'
 197   - '#size-cells'
 198
 199 patternProperties:
 200   "^adc@[0-9]+$":
 201     type: object
 202     description:
 203       An ADC block node should contain at least one subnode, representing an
 204       ADC instance available on the machine.
 205
 206     properties:
 207       compatible:
 208         enum:
 209           - st,stm32f4-adc
 210           - st,stm32h7-adc
 211           - st,stm32mp1-adc
 212
 213       reg:
 214         description: |
 215           Offset of ADC instance in ADC block. Valid values are:
 216             - 0x0:   ADC1
 217             - 0x100: ADC2
 218             - 0x200: ADC3 (stm32f4 only)
 219         maxItems: 1
 220
 221       '#io-channel-cells':
 222         const: 1
 223
 224       interrupts:
 225         description: |
 226           IRQ Line for the ADC instance. Valid values are:
 227             - 0 for adc@0
 228             - 1 for adc@100
 229             - 2 for adc@200 (stm32f4 only)
 230         maxItems: 1
 231
 232       clocks:
 233         description:
 234           Input clock private to this ADC instance. It's required only on
 235           stm32f4, that has per instance clock input for registers access.
 236         maxItems: 1
 237
 238       dmas:
 239         description: RX DMA Channel
 240         maxItems: 1
 241
 242       dma-names:
 243         const: rx
 244
 245       assigned-resolution-bits:
 246         description: |
 247           Resolution (bits) to use for conversions:
 248             - can be 6, 8, 10 or 12 on stm32f4
 249             - can be 8, 10, 12, 14 or 16 on stm32h7 and stm32mp1
 250         allOf:
 251           - $ref: /schemas/types.yaml#/definitions/uint32
 252
 253       st,adc-channels:
 254         description: |
 255           List of single-ended channels muxed for this ADC. It can have up to:
 256             - 16 channels, numbered from 0 to 15 (for in0..in15) on stm32f4
 257             - 20 channels, numbered from 0 to 19 (for in0..in19) on stm32h7 and
 258               stm32mp1.
 259         allOf:
 260           - $ref: /schemas/types.yaml#/definitions/uint32-array
 261
 262       st,adc-diff-channels:
 263         description: |
 264           List of differential channels muxed for this ADC. Some channels can
 265           be configured as differential instead of single-ended on stm32h7 and
 266           on stm32mp1. Positive and negative inputs pairs are listed:
 267           <vinp vinn>, <vinp vinn>,... vinp and vinn are numbered from 0 to 19.
 268
 269           Note: At least one of "st,adc-channels" or "st,adc-diff-channels" is
 270           required. Both properties can be used together. Some channels can be
 271           used as single-ended and some other ones as differential (mixed). But
 272           channels can't be configured both as single-ended and differential.
 273         allOf:
 274           - $ref: /schemas/types.yaml#/definitions/uint32-matrix
 275           - items:
 276               items:
 277                 - description: |
 278                     "vinp" indicates positive input number
 279                   minimum: 0
 280                   maximum: 19
 281                 - description: |
 282                     "vinn" indicates negative input number
 283                   minimum: 0
 284                   maximum: 19
 285
 286       st,min-sample-time-nsecs:
 287         description:
 288           Minimum sampling time in nanoseconds. Depending on hardware (board)
 289           e.g. high/low analog input source impedance, fine tune of ADC
 290           sampling time may be recommended. This can be either one value or an
 291           array that matches "st,adc-channels" and/or "st,adc-diff-channels"
 292           list, to set sample time resp. for all channels, or independently for
 293           each channel.
 294         allOf:
 295           - $ref: /schemas/types.yaml#/definitions/uint32-array
 296
 297     allOf:
 298       - if:
 299           properties:
 300             compatible:
 301               contains:
 302                 const: st,stm32f4-adc
 303
 304         then:
 305           properties:
 306             reg:
 307               enum:
 308                 - 0x0
 309                 - 0x100
 310                 - 0x200
 311
 312             interrupts:
 313               minimum: 0
 314               maximum: 2
 315
 316             assigned-resolution-bits:
 317               enum: [6, 8, 10, 12]
 318               default: 12
 319
 320             st,adc-channels:
 321               minItems: 1
 322               maxItems: 16
 323               items:
 324                 minimum: 0
 325                 maximum: 15
 326
 327             st,adc-diff-channels: false
 328
 329             st,min-sample-time-nsecs:
 330               minItems: 1
 331               maxItems: 16
 332               items:
 333                 minimum: 80
 334
 335           required:
 336             - clocks
 337
 338       - if:
 339           properties:
 340             compatible:
 341               contains:
 342                 enum:
 343                   - st,stm32h7-adc
 344                   - st,stm32mp1-adc
 345
 346         then:
 347           properties:
 348             reg:
 349               enum:
 350                 - 0x0
 351                 - 0x100
 352
 353             interrupts:
 354               minimum: 0
 355               maximum: 1
 356
 357             assigned-resolution-bits:
 358               enum: [8, 10, 12, 14, 16]
 359               default: 16
 360
 361             st,adc-channels:
 362               minItems: 1
 363               maxItems: 20
 364               items:
 365                 minimum: 0
 366                 maximum: 19
 367
 368             st,min-sample-time-nsecs:
 369               minItems: 1
 370               maxItems: 20
 371               items:
 372                 minimum: 40
 373
 374     additionalProperties: false
 375
 376     anyOf:
 377       - required:
 378           - st,adc-channels
 379       - required:
 380           - st,adc-diff-channels
 381
 382     required:
 383       - compatible
 384       - reg
 385       - interrupts
 386       - '#io-channel-cells'
 387
 388 examples:
 389   - |
 390     // Example 1: with stm32f429, ADC1, single-ended channel 8
 391       adc123: adc@40012000 {
 392         compatible = "st,stm32f4-adc-core";
 393         reg = <0x40012000 0x400>;
 394         interrupts = <18>;
 395         clocks = <&rcc 0 168>;
 396         clock-names = "adc";
 397         st,max-clk-rate-hz = <36000000>;
 398         vdda-supply = <&vdda>;
 399         vref-supply = <&vref>;
 400         interrupt-controller;
 401         #interrupt-cells = <1>;
 402         #address-cells = <1>;
 403         #size-cells = <0>;
 404         adc@0 {
 405           compatible = "st,stm32f4-adc";
 406           #io-channel-cells = <1>;
 407           reg = <0x0>;
 408           clocks = <&rcc 0 168>;
 409           interrupt-parent = <&adc123>;
 410           interrupts = <0>;
 411           st,adc-channels = <8>;
 412           dmas = <&dma2 0 0 0x400 0x0>;
 413           dma-names = "rx";
 414           assigned-resolution-bits = <8>;
 415         };
 416         // ...
 417         // other adc child nodes follow...
 418       };
 419
 420   - |
 421     // Example 2: with stm32mp157c to setup ADC1 with:
 422     // - channels 0 & 1 as single-ended
 423     // - channels 2 & 3 as differential (with resp. 6 & 7 negative inputs)
 424       #include <dt-bindings/interrupt-controller/arm-gic.h>
 425       #include <dt-bindings/clock/stm32mp1-clks.h>
 426       adc12: adc@48003000 {
 427         compatible = "st,stm32mp1-adc-core";
 428         reg = <0x48003000 0x400>;
 429         interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>,
 430                      <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>;
 431         clocks = <&rcc ADC12>, <&rcc ADC12_K>;
 432         clock-names = "bus", "adc";
 433         booster-supply = <&booster>;
 434         vdd-supply = <&vdd>;
 435         vdda-supply = <&vdda>;
 436         vref-supply = <&vref>;
 437         st,syscfg = <&syscfg>;
 438         interrupt-controller;
 439         #interrupt-cells = <1>;
 440         #address-cells = <1>;
 441         #size-cells = <0>;
 442         adc@0 {
 443           compatible = "st,stm32mp1-adc";
 444           #io-channel-cells = <1>;
 445           reg = <0x0>;
 446           interrupt-parent = <&adc12>;
 447           interrupts = <0>;
 448           st,adc-channels = <0 1>;
 449           st,adc-diff-channels = <2 6>, <3 7>;
 450           st,min-sample-time-nsecs = <5000>;
 451           dmas = <&dmamux1 9 0x400 0x05>;
 452           dma-names = "rx";
 453         };
 454         // ...
 455         // other adc child node follow...
 456       };
 457
 458 ...