Last edited one week ago

MDF device tree configuration

Applicable for STM32MP25x lines


1. Article purpose[edit source]

The purpose of this article is to explain how to configure the MDF internal peripheral using the device tree mechanism, relying on the bindings documentation, that is the description of the required and optional device-tree properties.

If the peripheral is assigned to another execution context, refer to How to assign an internal peripheral to an execution context article for guidelines on peripheral assignment and configuration.

2. DT bindings documentation[edit source]

Linux® OS: STM32 MDF device tree bindings: Documentation/devicetree/bindings/iio/adc/st,stm32-mdf-adc.yaml .

3. DT configuration[edit source]

This hardware description is a combination of the STM32 microprocessor device tree files (.dtsi extension) and board device tree files (.dts extension). See the Device tree for an explanation of the device-tree file organization.

The STM32CubeMX can be used to generate the board device tree. Refer to How to configure the DT using STM32CubeMX for more details.

3.1. DT configuration (STM32/SoC level)[edit source]

The MDF node is located in the device tree file for the software components, supporting the peripheral and listed in the above DT bindings documentation paragraph.

The MDF node is declared in stm32mp251.dtsi[1].

  • DT root node ('mdf') describes the MDF hardware block common parameters such as registers area, reset, clocks, power domain and pins.
  • DT child nodes ('sitf0', 'sitf1', ...) describe each serial interface independently: compatible string, registers area, pins ...
  • DT child nodes ('filter0', 'filter1', ...) describe each filter path independently: compatible string, registers area, interrupts, DMAs ...
mdf: mdf@404d0000 {
	compatible = "st,stm32mp25-mdf";
	...  /* common resources in 'mdf' root node. */
	sitf0: sitf@80 {
		compatible = "st,stm32mp25-sitf-mdf";
		...  /* private resources in serial interface 0 child node. */
	};
	filter0: filter@84 {
		compatible = "st,stm32mp25-mdf-dmic";  /* Compatible for audio driver */
		...  /* private resources in filter 0 child node. */
	}
};
Warning white.png Warning
This device tree part is related to STM32 microprocessors. It should be kept as is, without being modified by the end-user.

3.2. DT configuration (board level)[edit source]

The objective of this chapter is to explain how to enable and configure the MDF DT nodes for a board. The peripheral configuration should be done in specific board device tree files (board dts file and pinctrl dtsi file).

3.2.1. Common resources for all MDF filters[edit source]

Configure the 'mdf1' DT root node:

  • Enable the DT root node for the MDF, by setting status = "okay".
  • Optionally configure the MDF as a clock provider (e.g. to feed external MEMS microphones), as shown in MDF output clock example.
&mdf1 {
	status = "okay";
};

3.2.2. Private resources for each MDF serial interface[edit source]

Configure the sitf(s) DT child node(s):

  • Enable the SITF child node for the MDF, by setting status = "okay".
  • Configure the pin for input bitstream, via pinctrl, by setting pinctrl-0, pinctrl-1 and pinctrl-names. Also used to configure a pin for optional input clock.
  • Configure serial interface protocol, by setting st,sitf-mode property.
  • Optionally configure the serial interface as a clock consumer, as shown in MDF output clock example.
&mdf1 {
 	...
	sitf6: sitf@380 {
		pinctrl-names = "default", "sleep";
		pinctrl-0 = <&mdf_sdi6_test_pins_a>;
		pinctrl-1 = <&mdf_sdi6_sleep_test_pins_a>;
		st,sitf-mode = "spi";
		status = "okay";
	};
};

3.2.3. Private resources for each MDF filter[edit source]

Configure the filter(s) DT child node(s):

  • Enable the filter child node for the MDF, by setting status = "okay".
  • Configure the input bitstream serial interface source, by setting st,sitf property.
  • Configure CIC filter order, by setting st,cic-mode property.
  • Optionally configure more filter parameters acording to DT bindings documentation
  • Optionally configure more filter parameters acording to DT bindings documentation
    OMO: done }}
&mdf1 {
 	...
	filter0: filter@84  {
		st,cic-mode = <5>;
		st,sitf = <&sitf5 0>; /* Parameter sets the clock active edge for SPI modes. 0/1 for rising/falling edge*/
		status = "okay";
	};
 };

3.2.4. Additional configuration for MDF audio[edit source]

If the MDF peripheral is used for Audio capture, then additional child nodes must be added for audio soundcard configuration.

3.3. DT configuration examples[edit source]

3.3.1. MDF audio output clock DT configuration example[edit source]

The following example shows how to record from a digital microphone feed by the CCK0 clock provided by the MDF.


&mdf1 {
	pinctrl-names = "default", "sleep";
	pinctrl-0 = <&mdf_cck0_test_pins_a>;  /* Configure output pin for CCK0 clock */
	pinctrl-1 = <&mdf_cck0_sleep_test_pins_a>;
	#clock-cells = <1>;  /* Set MDF as clock provider */
	clock-output-names = "cck0";  /* Enable cck0 output clock to feed digital microphones */
	clock-frequency = <2048000>;  /* Set cck0 output clock to 2048 kHz */
 	...

	sitf5: sitf@300 {
		compatible = "st,stm32mp25-sitf-mdf";
		st,sitf-mode = "spi";  /* Set SPI protocol on serial interface5 */
		clocks = <&mdf1 0>;  /* Set cck0 as input clock for serial interface5 */
	};

	filter0: filter@84  {
		compatible = "st,stm32mp25-mdf-dmic";
		st,cic-mode = <5>;  /* Set CIC filter sync5 mode */
		st,sitf = <&sitf5 0>;  /* Feed filter0 with Input data from serial interface5 on clock rising edge */

		asoc_pdm0: mdf-dai {
			compatible = "st,stm32mp25-mdf-dai";
			io-channels = <&filter0 0>;  /* Feed digital audio interface with filter0 samples */

			mdf1_port0: port { ... };
		};
	};

3.3.2. MDF audio interleaved channels configuration example[edit source]

Below is an example that demonstrates the configuration of the MDF for capturing samples from two digital microphones. The interleaved data can be retrieved on a single ALSA stereo device.

Info white.png Information
This example can be expanded to capture samples from N microphones, but with the condition that the first filter must be filter0 and the subsequent filters must have consecutive indexes up to N-1.
&mdf1 {
	st,interleave = <&filter0 &filter1>;  /* Configure filter0 and filter1 as interleaved */
	...

	filter0: filter@84  {
		st,sitf = <&sitf5 0>;  /* Select data from serial interface 5 on clock rising edge */
		...

		asoc_pdm0: mdf-dai {
			io-channels = <&filter0 0>;  /* Filter0 provides interleaved stereo data to the ALSA audio device */

			mdf1_port0: port {
				mdf_endpoint0: endpoint {
					remote-endpoint = <&dmic0_endpoint>;
				};
			};
		};
	};

	filter1: filter@104  {
		st,sitf = <&sitf5 1>;  /* Select data from serial interface 5 on clock falling edge */
		                       /* Inherit other configurations from filter0 */
	};

	dmic0: dmic-0 {
		num-channels = <2>;  /* Stereo dmic codec */
		...
	};

3.3.3. MDF audio synchronous channels configuration example[edit source]

This example shows how to configure the MDF to capture data from two digital microphones, and retrieve the data synchronously on two ALSA audio devices. The typical use is to launch filter3 first, waiting from acquisition on filter2 to start.

&mdf1 {
	...

	filter2: filter@184  {
		st,sitf = <&sitf6 0>;
		...

		asoc_pdm2: mdf-dai {
			io-channels = <&filter2 0>;

			mdf1_port2: port {};
		};
	};

	filter3: filter@204  {
		st,sitf = <&sitf6 1>;
		st,sync = <&filter2>;  /* Synchronize filter3 with filter2 */

		asoc_pdm3: mdf-dai {
			io-channels = <&filter3 0>;

			mdf1_port3: port {};
		};
	};

4. How to configure the DT using STM32CubeMX[edit source]

The STM32CubeMX tool can be used to configure the STM32MPU device and get the corresponding platform configuration device tree files.
STM32CubeMX may not support all the properties described in DT binding files listed in the above DT bindings documentation paragraph. If so, the tool inserts user sections in the generated device tree. These sections can then be edited to add some properties, and they are preserved from one generation to another. Refer to STM32CubeMX user manual for further information.

5. References[edit source]

Please refer to the following links for additional information: