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@foss.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
 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
 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       '#address-cells':
 224         const: 1
 225
 226       '#size-cells':
 227         const: 0
 228
 229       interrupts:
 230         description: |
 231           IRQ Line for the ADC instance. Valid values are:
 232             - 0 for adc@0
 233             - 1 for adc@100
 234             - 2 for adc@200 (stm32f4 only)
 235         maxItems: 1
 236
 237       clocks:
 238         description:
 239           Input clock private to this ADC instance. It's required only on
 240           stm32f4, that has per instance clock input for registers access.
 241         maxItems: 1
 242
 243       dmas:
 244         description: RX DMA Channel
 245         maxItems: 1
 246
 247       dma-names:
 248         const: rx
 249
 250       assigned-resolution-bits:
 251         description: |
 252           Resolution (bits) to use for conversions:
 253             - can be 6, 8, 10 or 12 on stm32f4
 254             - can be 8, 10, 12, 14 or 16 on stm32h7 and stm32mp1
 255
 256       st,adc-channels:
 257         description: |
 258           List of single-ended channels muxed for this ADC. It can have up to:
 259             - 16 channels, numbered from 0 to 15 (for in0..in15) on stm32f4
 260             - 20 channels, numbered from 0 to 19 (for in0..in19) on stm32h7 and
 261               stm32mp1.
 262         $ref: /schemas/types.yaml#/definitions/uint32-array
 263         deprecated: true
 264
 265       st,adc-diff-channels:
 266         description: |
 267           List of differential channels muxed for this ADC. Some channels can
 268           be configured as differential instead of single-ended on stm32h7 and
 269           on stm32mp1. Positive and negative inputs pairs are listed:
 270           <vinp vinn>, <vinp vinn>,... vinp and vinn are numbered from 0 to 19.
 271
 272           Note: At least one of "st,adc-channels" or "st,adc-diff-channels" is
 273           required if no adc generic channel is defined. These legacy channel
 274           properties are exclusive with adc generic channel bindings.
 275           Both properties can be used together. Some channels can be
 276           used as single-ended and some other ones as differential (mixed). But
 277           channels can't be configured both as single-ended and differential.
 278         $ref: /schemas/types.yaml#/definitions/uint32-matrix
 279         items:
 280           items:
 281             - description: |
 282                 "vinp" indicates positive input number
 283               minimum: 0
 284               maximum: 19
 285             - description: |
 286                 "vinn" indicates negative input number
 287               minimum: 0
 288               maximum: 19
 289         deprecated: true
 290
 291       st,min-sample-time-nsecs:
 292         description:
 293           Minimum sampling time in nanoseconds. Depending on hardware (board)
 294           e.g. high/low analog input source impedance, fine tune of ADC
 295           sampling time may be recommended. This can be either one value or an
 296           array that matches "st,adc-channels" and/or "st,adc-diff-channels"
 297           list, to set sample time resp. for all channels, or independently for
 298           each channel.
 299         $ref: /schemas/types.yaml#/definitions/uint32-array
 300         deprecated: true
 301
 302       nvmem-cells:
 303         items:
 304           - description: Phandle to the calibration vrefint data provided by otp
 305
 306       nvmem-cell-names:
 307         items:
 308           - const: vrefint
 309
 310     patternProperties:
 311       "^channel@([0-9]|1[0-9])$":
 312         type: object
 313         $ref: "adc.yaml"
 314         description: Represents the external channels which are connected to the ADC.
 315
 316         properties:
 317           reg:
 318             items:
 319               minimum: 0
 320               maximum: 19
 321
 322           label:
 323             description: |
 324               Unique name to identify which channel this is.
 325               Reserved label names "vddcore", "vrefint" and "vbat"
 326               are used to identify internal channels with matching names.
 327
 328           diff-channels:
 329             $ref: /schemas/types.yaml#/definitions/uint32-array
 330             items:
 331               minimum: 0
 332               maximum: 19
 333
 334           st,min-sample-time-ns:
 335             description: |
 336               Minimum sampling time in nanoseconds. Depending on hardware (board)
 337               e.g. high/low analog input source impedance, fine tune of ADC
 338               sampling time may be recommended.
 339
 340         required:
 341           - reg
 342
 343         additionalProperties: false
 344
 345     allOf:
 346       - if:
 347           properties:
 348             compatible:
 349               contains:
 350                 const: st,stm32f4-adc
 351
 352         then:
 353           properties:
 354             reg:
 355               enum:
 356                 - 0x0
 357                 - 0x100
 358                 - 0x200
 359
 360             interrupts:
 361               minimum: 0
 362               maximum: 2
 363
 364             assigned-resolution-bits:
 365               enum: [6, 8, 10, 12]
 366               default: 12
 367
 368             st,adc-channels:
 369               minItems: 1
 370               maxItems: 16
 371               items:
 372                 minimum: 0
 373                 maximum: 15
 374
 375             st,adc-diff-channels: false
 376
 377             st,min-sample-time-nsecs:
 378               minItems: 1
 379               maxItems: 16
 380               items:
 381                 minimum: 80
 382
 383           required:
 384             - clocks
 385
 386       - if:
 387           properties:
 388             compatible:
 389               contains:
 390                 enum:
 391                   - st,stm32h7-adc
 392                   - st,stm32mp1-adc
 393
 394         then:
 395           properties:
 396             reg:
 397               enum:
 398                 - 0x0
 399                 - 0x100
 400
 401             interrupts:
 402               minimum: 0
 403               maximum: 1
 404
 405             assigned-resolution-bits:
 406               enum: [8, 10, 12, 14, 16]
 407               default: 16
 408
 409             st,adc-channels:
 410               minItems: 1
 411               maxItems: 20
 412               items:
 413                 minimum: 0
 414                 maximum: 19
 415
 416             st,min-sample-time-nsecs:
 417               minItems: 1
 418               maxItems: 20
 419               items:
 420                 minimum: 40
 421
 422     additionalProperties: false
 423
 424     required:
 425       - compatible
 426       - reg
 427       - interrupts
 428       - '#io-channel-cells'
 429
 430 examples:
 431   - |
 432     // Example 1: with stm32f429, ADC1, single-ended channel 8
 433       adc123: adc@40012000 {
 434         compatible = "st,stm32f4-adc-core";
 435         reg = <0x40012000 0x400>;
 436         interrupts = <18>;
 437         clocks = <&rcc 0 168>;
 438         clock-names = "adc";
 439         st,max-clk-rate-hz = <36000000>;
 440         vdda-supply = <&vdda>;
 441         vref-supply = <&vref>;
 442         interrupt-controller;
 443         #interrupt-cells = <1>;
 444         #address-cells = <1>;
 445         #size-cells = <0>;
 446         adc@0 {
 447           compatible = "st,stm32f4-adc";
 448           #io-channel-cells = <1>;
 449           reg = <0x0>;
 450           clocks = <&rcc 0 168>;
 451           interrupt-parent = <&adc123>;
 452           interrupts = <0>;
 453           st,adc-channels = <8>;
 454           dmas = <&dma2 0 0 0x400 0x0>;
 455           dma-names = "rx";
 456           assigned-resolution-bits = <8>;
 457         };
 458         // ...
 459         // other adc child nodes follow...
 460       };
 461
 462   - |
 463     // Example 2: with stm32mp157c to setup ADC1 with:
 464     // - channels 0 & 1 as single-ended
 465     // - channels 2 & 3 as differential (with resp. 6 & 7 negative inputs)
 466       #include <dt-bindings/interrupt-controller/arm-gic.h>
 467       #include <dt-bindings/clock/stm32mp1-clks.h>
 468       adc12: adc@48003000 {
 469         compatible = "st,stm32mp1-adc-core";
 470         reg = <0x48003000 0x400>;
 471         interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>,
 472                      <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>;
 473         clocks = <&rcc ADC12>, <&rcc ADC12_K>;
 474         clock-names = "bus", "adc";
 475         booster-supply = <&booster>;
 476         vdd-supply = <&vdd>;
 477         vdda-supply = <&vdda>;
 478         vref-supply = <&vref>;
 479         st,syscfg = <&syscfg>;
 480         interrupt-controller;
 481         #interrupt-cells = <1>;
 482         #address-cells = <1>;
 483         #size-cells = <0>;
 484         adc@0 {
 485           compatible = "st,stm32mp1-adc";
 486           #io-channel-cells = <1>;
 487           reg = <0x0>;
 488           interrupt-parent = <&adc12>;
 489           interrupts = <0>;
 490           st,adc-channels = <0 1>;
 491           st,adc-diff-channels = <2 6>, <3 7>;
 492           st,min-sample-time-nsecs = <5000>;
 493           dmas = <&dmamux1 9 0x400 0x05>;
 494           dma-names = "rx";
 495         };
 496         // ...
 497         // other adc child node follow...
 498       };
 499
 500   - |
 501     // Example 3: with stm32mp157c to setup ADC2 with:
 502     // - internal channels 13, 14, 15.
 503       #include <dt-bindings/interrupt-controller/arm-gic.h>
 504       #include <dt-bindings/clock/stm32mp1-clks.h>
 505       adc122: adc@48003000 {
 506         compatible = "st,stm32mp1-adc-core";
 507         reg = <0x48003000 0x400>;
 508         interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>,
 509                      <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>;
 510         clocks = <&rcc ADC12>, <&rcc ADC12_K>;
 511         clock-names = "bus", "adc";
 512         booster-supply = <&booster>;
 513         vdd-supply = <&vdd>;
 514         vdda-supply = <&vdda>;
 515         vref-supply = <&vref>;
 516         st,syscfg = <&syscfg>;
 517         interrupt-controller;
 518         #interrupt-cells = <1>;
 519         #address-cells = <1>;
 520         #size-cells = <0>;
 521         adc@100 {
 522           compatible = "st,stm32mp1-adc";
 523           #io-channel-cells = <1>;
 524           reg = <0x100>;
 525           interrupts = <1>;
 526           #address-cells = <1>;
 527           #size-cells = <0>;
 528           channel@13 {
 529             reg = <13>;
 530             label = "vrefint";
 531             st,min-sample-time-ns = <9000>;
 532           };
 533           channel@14 {
 534             reg = <14>;
 535             label = "vddcore";
 536             st,min-sample-time-ns = <9000>;
 537           };
 538           channel@15 {
 539             reg = <15>;
 540             label = "vbat";
 541             st,min-sample-time-ns = <9000>;
 542           };
 543         };
 544       };
 545
 546 ...