xref: /freebsd/sys/contrib/device-tree/Bindings/iio/adc/st,stm32-adc.yaml (revision 7ef62cebc2f965b0f640263e179276928885e33d) 
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
7title: STMicroelectronics STM32 ADC bindings
8
9description: |
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
21maintainers:
22  - Fabrice Gasnier <fabrice.gasnier@foss.st.com>
23
24properties:
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
94allOf:
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
183additionalProperties: false
184
185required:
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
198patternProperties:
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
430examples:
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...
547