xref: /freebsd/sys/contrib/device-tree/Bindings/iio/adc/st,stm32-adc.yaml (revision 4e579ad047720775ab580b74192c7de8a3386fea) 
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
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      - st,stm32mp13-adc-core
31
32  reg:
33    maxItems: 1
34
35  interrupts:
36    description: |
37      One or more interrupts for ADC block, depending on part used:
38        - stm32f4 and stm32h7 share a common ADC interrupt line.
39        - stm32mp1 has two separate interrupt lines, one for each ADC within
40          ADC block.
41        - stm32mp13 has an interrupt line per ADC block.
42    minItems: 1
43    maxItems: 2
44
45  clocks:
46    minItems: 1
47    maxItems: 2
48    description: |
49      Core can use up to two clocks, depending on part used:
50        - "adc" clock: for the analog circuitry, common to all ADCs.
51          It's required on stm32f4.
52          It's optional on stm32h7 and stm32mp1.
53        - "bus" clock: for registers access, common to all ADCs.
54          It's not present on stm32f4.
55          It's required on stm32h7 and stm32mp1.
56
57  clock-names: true
58
59  st,max-clk-rate-hz:
60    description:
61      Allow to specify desired max clock rate used by analog circuitry.
62
63  vdda-supply:
64    description: Phandle to the vdda input analog voltage.
65
66  vref-supply:
67    description: Phandle to the vref input analog reference voltage.
68
69  booster-supply:
70    description:
71      Phandle to the embedded booster regulator that can be used to supply ADC
72      analog input switches on stm32h7 and stm32mp1.
73
74  vdd-supply:
75    description:
76      Phandle to the vdd input voltage. It can be used to supply ADC analog
77      input switches on stm32mp1.
78
79  st,syscfg:
80    description:
81      Phandle to system configuration controller. It can be used to control the
82      analog circuitry on stm32mp1.
83    $ref: /schemas/types.yaml#/definitions/phandle-array
84
85  interrupt-controller: true
86
87  '#interrupt-cells':
88    const: 1
89
90  '#address-cells':
91    const: 1
92
93  '#size-cells':
94    const: 0
95
96allOf:
97  - if:
98      properties:
99        compatible:
100          contains:
101            const: st,stm32f4-adc-core
102
103    then:
104      properties:
105        clocks:
106          maxItems: 1
107
108        clock-names:
109          const: adc
110
111        interrupts:
112          items:
113            - description: interrupt line common for all ADCs
114
115        st,max-clk-rate-hz:
116          minimum: 600000
117          maximum: 36000000
118          default: 36000000
119
120        booster-supply: false
121
122        vdd-supply: false
123
124        st,syscfg: false
125
126  - if:
127      properties:
128        compatible:
129          contains:
130            const: st,stm32h7-adc-core
131
132    then:
133      properties:
134        clocks:
135          minItems: 1
136          maxItems: 2
137
138        clock-names:
139          items:
140            - const: bus
141            - const: adc
142          minItems: 1
143
144        interrupts:
145          items:
146            - description: interrupt line common for all ADCs
147
148        st,max-clk-rate-hz:
149          minimum: 120000
150          maximum: 36000000
151          default: 36000000
152
153        vdd-supply: false
154
155        st,syscfg: false
156
157  - if:
158      properties:
159        compatible:
160          contains:
161            const: st,stm32mp1-adc-core
162
163    then:
164      properties:
165        clocks:
166          minItems: 1
167          maxItems: 2
168
169        clock-names:
170          items:
171            - const: bus
172            - const: adc
173          minItems: 1
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  - if:
186      properties:
187        compatible:
188          contains:
189            const: st,stm32mp13-adc-core
190
191    then:
192      properties:
193        clocks:
194          minItems: 1
195          maxItems: 2
196
197        clock-names:
198          items:
199            - const: bus
200            - const: adc
201          minItems: 1
202
203        interrupts:
204          items:
205            - description: ADC interrupt line
206
207        st,max-clk-rate-hz:
208          minimum: 150000
209          maximum: 75000000
210          default: 75000000
211
212additionalProperties: false
213
214required:
215  - compatible
216  - reg
217  - interrupts
218  - clocks
219  - clock-names
220  - vdda-supply
221  - vref-supply
222  - interrupt-controller
223  - '#interrupt-cells'
224  - '#address-cells'
225  - '#size-cells'
226
227patternProperties:
228  "^adc@[0-9]+$":
229    type: object
230    description:
231      An ADC block node should contain at least one subnode, representing an
232      ADC instance available on the machine.
233
234    properties:
235      compatible:
236        enum:
237          - st,stm32f4-adc
238          - st,stm32h7-adc
239          - st,stm32mp1-adc
240          - st,stm32mp13-adc
241
242      reg:
243        description: |
244          Offset of ADC instance in ADC block. Valid values are:
245            - 0x0:   ADC1
246            - 0x100: ADC2
247            - 0x200: ADC3 (stm32f4 only)
248        maxItems: 1
249
250      '#io-channel-cells':
251        const: 1
252
253      '#address-cells':
254        const: 1
255
256      '#size-cells':
257        const: 0
258
259      interrupts:
260        description: |
261          IRQ Line for the ADC instance. Valid values are:
262            - 0 for adc@0 (single adc for stm32mp13)
263            - 1 for adc@100
264            - 2 for adc@200 (stm32f4 only)
265        maxItems: 1
266
267      clocks:
268        description:
269          Input clock private to this ADC instance. It's required only on
270          stm32f4, that has per instance clock input for registers access.
271        maxItems: 1
272
273      dmas:
274        description: RX DMA Channel
275        maxItems: 1
276
277      dma-names:
278        const: rx
279
280      assigned-resolution-bits:
281        description: |
282          Resolution (bits) to use for conversions:
283            - can be 6, 8, 10 or 12 on stm32f4 and stm32mp13
284            - can be 8, 10, 12, 14 or 16 on stm32h7 and stm32mp1
285
286      st,adc-channels:
287        description: |
288          List of single-ended channels muxed for this ADC. It can have up to:
289            - 16 channels, numbered from 0 to 15 (for in0..in15) on stm32f4
290            - 19 channels, numbered from 0 to 18 (for in0..in18) on stm32mp13.
291            - 20 channels, numbered from 0 to 19 (for in0..in19) on stm32h7 and
292              stm32mp1.
293        $ref: /schemas/types.yaml#/definitions/uint32-array
294        deprecated: true
295
296      st,adc-diff-channels:
297        description: |
298          List of differential channels muxed for this ADC. Some channels can
299          be configured as differential instead of single-ended on stm32h7 and
300          on stm32mp1. Positive and negative inputs pairs are listed:
301          <vinp vinn>, <vinp vinn>,... vinp and vinn are numbered from 0 to 19.
302
303          Note: At least one of "st,adc-channels" or "st,adc-diff-channels" is
304          required if no adc generic channel is defined. These legacy channel
305          properties are exclusive with adc generic channel bindings.
306          Both properties can be used together. Some channels can be
307          used as single-ended and some other ones as differential (mixed). But
308          channels can't be configured both as single-ended and differential.
309        $ref: /schemas/types.yaml#/definitions/uint32-matrix
310        items:
311          items:
312            - description: |
313                "vinp" indicates positive input number
314              minimum: 0
315              maximum: 19
316            - description: |
317                "vinn" indicates negative input number
318              minimum: 0
319              maximum: 19
320        deprecated: true
321
322      st,min-sample-time-nsecs:
323        description:
324          Minimum sampling time in nanoseconds. Depending on hardware (board)
325          e.g. high/low analog input source impedance, fine tune of ADC
326          sampling time may be recommended. This can be either one value or an
327          array that matches "st,adc-channels" and/or "st,adc-diff-channels"
328          list, to set sample time resp. for all channels, or independently for
329          each channel.
330        $ref: /schemas/types.yaml#/definitions/uint32-array
331        deprecated: true
332
333      nvmem-cells:
334        items:
335          - description: Phandle to the calibration vrefint data provided by otp
336
337      nvmem-cell-names:
338        items:
339          - const: vrefint
340
341    patternProperties:
342      "^channel@([0-9]|1[0-9])$":
343        type: object
344        $ref: adc.yaml
345        description: Represents the external channels which are connected to the ADC.
346
347        properties:
348          reg:
349            items:
350              minimum: 0
351              maximum: 19
352
353          label:
354            description: |
355              Unique name to identify which channel this is.
356              Reserved label names "vddcore", "vddcpu", "vddq_ddr", "vrefint" and "vbat"
357              are used to identify internal channels with matching names.
358
359          diff-channels:
360            $ref: /schemas/types.yaml#/definitions/uint32-array
361            items:
362              minimum: 0
363              maximum: 19
364
365          st,min-sample-time-ns:
366            description: |
367              Minimum sampling time in nanoseconds. Depending on hardware (board)
368              e.g. high/low analog input source impedance, fine tune of ADC
369              sampling time may be recommended.
370
371        required:
372          - reg
373
374        additionalProperties: false
375
376    allOf:
377      - if:
378          properties:
379            compatible:
380              contains:
381                const: st,stm32f4-adc
382
383        then:
384          properties:
385            reg:
386              enum:
387                - 0x0
388                - 0x100
389                - 0x200
390
391            interrupts:
392              minimum: 0
393              maximum: 2
394
395            assigned-resolution-bits:
396              enum: [6, 8, 10, 12]
397              default: 12
398
399            st,adc-channels:
400              minItems: 1
401              maxItems: 16
402              items:
403                minimum: 0
404                maximum: 15
405
406            st,adc-diff-channels: false
407
408            st,min-sample-time-nsecs:
409              minItems: 1
410              maxItems: 16
411              items:
412                minimum: 80
413
414          required:
415            - clocks
416
417      - if:
418          properties:
419            compatible:
420              contains:
421                enum:
422                  - st,stm32h7-adc
423                  - st,stm32mp1-adc
424
425        then:
426          properties:
427            reg:
428              enum:
429                - 0x0
430                - 0x100
431
432            interrupts:
433              minimum: 0
434              maximum: 1
435
436            assigned-resolution-bits:
437              enum: [8, 10, 12, 14, 16]
438              default: 16
439
440            st,adc-channels:
441              minItems: 1
442              maxItems: 20
443              items:
444                minimum: 0
445                maximum: 19
446
447            st,min-sample-time-nsecs:
448              minItems: 1
449              maxItems: 20
450              items:
451                minimum: 40
452
453
454      - if:
455          properties:
456            compatible:
457              contains:
458                const: st,stm32mp13-adc
459
460        then:
461          properties:
462            reg:
463              const: 0x0
464
465            interrupts:
466              const: 0
467
468            assigned-resolution-bits:
469              enum: [6, 8, 10, 12]
470              default: 12
471
472            st,adc-channels:
473              minItems: 1
474              maxItems: 19
475              items:
476                minimum: 0
477                maximum: 18
478
479            st,min-sample-time-nsecs:
480              minItems: 1
481              maxItems: 19
482              items:
483                minimum: 40
484    additionalProperties: false
485
486    required:
487      - compatible
488      - reg
489      - interrupts
490      - '#io-channel-cells'
491
492examples:
493  - |
494    // Example 1: with stm32f429, ADC1, single-ended channel 8
495      adc123: adc@40012000 {
496        compatible = "st,stm32f4-adc-core";
497        reg = <0x40012000 0x400>;
498        interrupts = <18>;
499        clocks = <&rcc 0 168>;
500        clock-names = "adc";
501        st,max-clk-rate-hz = <36000000>;
502        vdda-supply = <&vdda>;
503        vref-supply = <&vref>;
504        interrupt-controller;
505        #interrupt-cells = <1>;
506        #address-cells = <1>;
507        #size-cells = <0>;
508        adc@0 {
509          compatible = "st,stm32f4-adc";
510          #io-channel-cells = <1>;
511          reg = <0x0>;
512          clocks = <&rcc 0 168>;
513          interrupt-parent = <&adc123>;
514          interrupts = <0>;
515          st,adc-channels = <8>;
516          dmas = <&dma2 0 0 0x400 0x0>;
517          dma-names = "rx";
518          assigned-resolution-bits = <8>;
519        };
520        // ...
521        // other adc child nodes follow...
522      };
523
524  - |
525    // Example 2: with stm32mp157c to setup ADC1 with:
526    // - channels 0 & 1 as single-ended
527    // - channels 2 & 3 as differential (with resp. 6 & 7 negative inputs)
528      #include <dt-bindings/interrupt-controller/arm-gic.h>
529      #include <dt-bindings/clock/stm32mp1-clks.h>
530      adc12: adc@48003000 {
531        compatible = "st,stm32mp1-adc-core";
532        reg = <0x48003000 0x400>;
533        interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>,
534                     <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>;
535        clocks = <&rcc ADC12>, <&rcc ADC12_K>;
536        clock-names = "bus", "adc";
537        booster-supply = <&booster>;
538        vdd-supply = <&vdd>;
539        vdda-supply = <&vdda>;
540        vref-supply = <&vref>;
541        st,syscfg = <&syscfg>;
542        interrupt-controller;
543        #interrupt-cells = <1>;
544        #address-cells = <1>;
545        #size-cells = <0>;
546        adc@0 {
547          compatible = "st,stm32mp1-adc";
548          #io-channel-cells = <1>;
549          reg = <0x0>;
550          interrupt-parent = <&adc12>;
551          interrupts = <0>;
552          st,adc-channels = <0 1>;
553          st,adc-diff-channels = <2 6>, <3 7>;
554          st,min-sample-time-nsecs = <5000>;
555          dmas = <&dmamux1 9 0x400 0x05>;
556          dma-names = "rx";
557        };
558        // ...
559        // other adc child node follow...
560      };
561
562  - |
563    // Example 3: with stm32mp157c to setup ADC2 with:
564    // - internal channels 13, 14, 15.
565      #include <dt-bindings/interrupt-controller/arm-gic.h>
566      #include <dt-bindings/clock/stm32mp1-clks.h>
567      adc122: adc@48003000 {
568        compatible = "st,stm32mp1-adc-core";
569        reg = <0x48003000 0x400>;
570        interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>,
571                     <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>;
572        clocks = <&rcc ADC12>, <&rcc ADC12_K>;
573        clock-names = "bus", "adc";
574        booster-supply = <&booster>;
575        vdd-supply = <&vdd>;
576        vdda-supply = <&vdda>;
577        vref-supply = <&vref>;
578        st,syscfg = <&syscfg>;
579        interrupt-controller;
580        #interrupt-cells = <1>;
581        #address-cells = <1>;
582        #size-cells = <0>;
583        adc@100 {
584          compatible = "st,stm32mp1-adc";
585          #io-channel-cells = <1>;
586          reg = <0x100>;
587          interrupts = <1>;
588          #address-cells = <1>;
589          #size-cells = <0>;
590          channel@13 {
591            reg = <13>;
592            label = "vrefint";
593            st,min-sample-time-ns = <9000>;
594          };
595          channel@14 {
596            reg = <14>;
597            label = "vddcore";
598            st,min-sample-time-ns = <9000>;
599          };
600          channel@15 {
601            reg = <15>;
602            label = "vbat";
603            st,min-sample-time-ns = <9000>;
604          };
605        };
606      };
607
608...
609