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