xref: /freebsd/sys/contrib/device-tree/Bindings/iio/adc/st,stm32-adc.yaml (revision ec0ea6efa1ad229d75c394c1a9b9cac33af2b1d3) 
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@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          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
185additionalProperties: false
186
187required:
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
200patternProperties:
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
384examples:
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...
455