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