boards/shields: add support for x-nucleo-iks02a1 shield

x-nucleo-iks02a1 shield is an arduino compatible companion board
which can be used on top of Nucleo standard boards for industrial
applications. It extends the Nucleo functionalities adding following
MEMS sensor support:

    - ISM330DHCX 3-axis accelerometer and 3-axis gyroscope
    - IIS2MDC 3-axis magnetometer
    - IIS2DLPC 3-axis accelerometer
    - IMP34DT05 digital microphone.

Signed-off-by: Armando Visconti <armando.visconti@st.com>

boards/shields/x_nucleo_iks02a1/Kconfig.defconfig

@@ -0,0 +1,5 @@
+# Copyright (c) 2020 STMicroelectronics
+#
+# SPDX-License-Identifier: Apache-2.0
+
+rsource "boards/*.defconfig"

boards/shields/x_nucleo_iks02a1/Kconfig.shield

@@ -0,0 +1,5 @@
+# Copyright (c) 2020 STMicroelectronics
+# SPDX-License-Identifier: Apache-2.0
+
+config SHIELD_X_NUCLEO_IKS02A1
+	def_bool $(shields_list_contains,x_nucleo_iks02a1)

boards/shields/x_nucleo_iks02a1/boards/nucleo_f411re.defconfig

@@ -0,0 +1,45 @@
+# Copyright (c) 2020 STMicroelectronics
+#
+# SPDX-License-Identifier: Apache-2.0
+
+if BOARD_NUCLEO_F411RE
+
+if I2S
+
+# The I2S should be configured in such a way it generates a 2MHz
+# clock to the MP34DT05 microphone.
+#
+# The input clock to I2S block is I2SClk. This clock is generated
+# by the PLLI2S from either HSI or HSE osci using this formula:
+#
+#    Fin = HSE or HSI osci
+#    Fvco = Fin x (PLLN/PLLM)
+#    I2SClk = Fvco / PLLR
+#
+# For example, if Fin is HSE at 8MHz and PLLM=8, PLLN=192, PLLR=3,
+# the resulting I2SCLk is 64MHz. On the contrary if HSI at 16MHz is
+# used the resulting I2SClk frequency would be 128MHz.
+# The shield user is invited to verify which osci is configured on
+# Nucleo F441RE board defconfig file and calculate the final frequency.
+#
+# The I2S block then uses I2SDIV and I2SODD register fields to further
+# divide I2SClk. These parameters are automatically calculated by
+# I2S driver, in order to obtain the requested output @2MHz, so
+# having a I2SClk in input at 64MHz or 128MHz does not make a any
+# difference.
+
+config I2S_STM32_USE_PLLI2S_ENABLE
+	default y
+
+config I2S_STM32_PLLI2S_PLLM
+	default 8
+
+config I2S_STM32_PLLI2S_PLLN
+	default 192
+
+config I2S_STM32_PLLI2S_PLLR
+	default 3
+
+endif # I2S
+
+endif # BOARD_NUCLEO_F411RE

boards/shields/x_nucleo_iks02a1/boards/nucleo_f411re.overlay

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2020 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+&dma2 {
+	status = "okay";
+};

boards/shields/x_nucleo_iks02a1/doc/index.rst

@@ -0,0 +1,105 @@
+.. _x-nucleo-iks02a1:
+
+X-NUCLEO-IKS02A1: MEMS Inertial and Environmental Multi sensor shield
+#####################################################################
+
+Overview
+********
+The X-NUCLEO-IKS02A1 is a motion MEMS expansion board for the STM32 Nucleo,
+fitting the requirements of industrial applications.
+It is equipped with Arduino UNO R3 connector layout, and
+is designed around the ISM330DHCX 3-axis accelerometer and 3-axis gyroscope,
+the IIS2MDC 3-axis magnetometer, the IIS2DLPC 3-axis accelerometer and
+the IMP34DT05 digital microphone.
+
+The X-NUCLEO-IKS02A1 interfaces with the STM32 microcontroller via the I2C pin,
+and it is possible to change the default I2C port.
+
+.. image:: img/x-nucleo-iks02a1.jpg
+     :width: 426px
+     :height: 395px
+     :align: center
+     :alt: X-NUCLEO-IKS02A1
+
+More information about the board can be found at the
+`X-NUCLEO-IKS02A1 website`_.
+
+Hardware Description
+********************
+
+X-NUCLEO-IKS02A1 provides the following key features:
+
+ - ISM330DHCX MEMS 3D accelerometer (±2/±4/±8/±16 g) and
+   3D gyroscope (±125/±250/±500/±1000/±2000 dps)
+ - IIS2MDC MEMS 3D magnetometer (±50 gauss)
+ - IIS2DLPC MEMS 3D accelerometer low power (±2/±4/±8/±16 g)
+ - IMP34DT05 MEMS digital omnidirectional microphone (-26 dBFS, ±3 dB sensitivity)
+ - DIL24 socket for additional MEMS adapters and other sensors (configurable in I2C or SPI)
+ - I2C sensor hub features on ISM330DHCX available
+ - Compatible with STM32 Nucleo boards
+ - Equipped with Arduino UNO R3 connector
+ - RoHS compliant
+ - WEEE compliant
+
+Hardware Configuration
+**********************
+
+X-NUCLEO-IKS02A1 board connects the various devices on two separate I2C bus:
+
+- IIS2DLPC and ISM330DHCX are on I2C2
+- IIS2MDC is on I2C1
+
+X-NUCLEO-IKS02A1 board can be configured in two different hardware modes, Mode 1 and Mode 2,
+using the JP7/JP8 jumpers to modify to what the I2C1 bus connects to.
+
+
+Mode 1: Standard Mode
+=====================
+
+In standard I2C mode the two buses are connected together. As a consequence, all devices on the shield
+reside on the same I2C bus and are accessible from the main board mcu.
+
+The jumper configuration to activate this mode is:
+
+- JP7 => 1-2, 3-4 (I2C1 = I2C2, I2Cx=GND)
+- JP8 => 1-2, 3-4 (I2C1 = I2C2, I2Cx=GND)
+
+
+Mode 2: SensorHub Mode
+======================
+
+In SensorHub mode ISM330DHCX and IIS2DLPC are connected to I2C2 and are accessible from the main board mcu.
+Instead, the IIS2MDC device is connected only to ISM330DHCX sensor thru its SCx/SDX (I2Cx) pins.
+
+The jumper configuration to activate this mode is:
+
+- JP7 => 2-3 (I2C1 = I2Cx)
+- JP8 => 2-3 (I2C1 = I2Cx)
+
+More information about X-NUCLEO-IKS02A1 configuration modes can be found in the
+`X-NUCLEO-IKS02A1 user manual`_
+
+Programming
+***********
+
+Three samples are provided as examples for ``x-nucleo-iks02a1`` shield:
+
+- :ref:`x-nucleo-iks02a1-std-sample` application, to be used when the shield is configured
+  in Standard Mode
+- :ref:`x-nucleo-iks02a1-shub-sample` application, to be used when the shield is configured
+  in SensorHub Mode
+- :ref:`x-nucleo-iks02a1-mic-sample` application, to be used to acquire data through the
+  on-board PDM microphone
+
+See also :ref:`shields` for more details.
+
+References
+**********
+
+.. target-notes::
+
+.. _X-NUCLEO-IKS02A1 website:
+   http://www.st.com/en/ecosystems/x-nucleo-iks02a1.html
+
+.. _X-NUCLEO-IKS02A1 user manual:
+   https://www.st.com/resource/en/user_manual/DM00651686.pdf

boards/shields/x_nucleo_iks02a1/x_nucleo_iks02a1.overlay

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2020 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * Mode 1: Standard Mode
+ *
+ *   JP7 => 1-2, 3-4 (I2C1 = I2C2, I2Cx=GND)
+ *   JP8 => 1-2, 3-4 (I2C1 = I2C2, I2Cx=GND)
+ *
+ * ISM330DHCX, IIS2MDC and IIS2DLPC sensors are accessible from the main board mcu.
+ */
+
+&arduino_i2c {
+
+	iis2dlpc@19 {
+		compatible = "st,iis2dlpc";
+		reg = <0x19>;
+		drdy-gpios =  <&arduino_header 4 GPIO_ACTIVE_HIGH>; /* A4 - INT2 */
+		label = "IIS2DLPC";
+	};
+
+	iis2mdc@1e {
+		compatible = "st,iis2mdc";
+		reg = <0x1e>;
+		drdy-gpios =  <&arduino_header 2 GPIO_ACTIVE_HIGH>; /* A2 */
+		label = "IIS2MDC";
+	};
+
+	ism330dhcx@6b {
+		compatible = "st,ism330dhcx";
+		reg = <0x6b>;
+		drdy-gpios =  <&arduino_header 11 GPIO_ACTIVE_HIGH>; /* D5 - INT2 */
+		label = "ISM330DHCX";
+	};
+};

boards/shields/x_nucleo_iks02a1/x_nucleo_iks02a1_mic.overlay

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2020 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+&arduino_i2s {
+	status = "okay";
+
+	mp34dt05@0 {
+		compatible = "st,mpxxdtyy";
+		reg = <0>;
+		label = "MP34DT05";
+	};
+};

boards/shields/x_nucleo_iks02a1/x_nucleo_iks02a1_shub.overlay

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2020 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * Mode 2: SensorHub Mode
+ *
+ *   JP7 => 2-3 (I2C1 = I2Cx)
+ *   JP8 => 2-3 (I2C1 = I2Cx)
+ *
+ * Only ISM330DHCX and IIS2DLPC sensors are accessible from the main board mcu.
+ * IIS2MDC is connected directly to ISM330DHCX SCx/SDX (I2Cx) pins, so it is not
+ * declared in DTS file.
+ */
+
+&arduino_i2c {
+
+	iis2dlpc@19 {
+		compatible = "st,iis2dlpc";
+		reg = <0x19>;
+		drdy-gpios =  <&arduino_header 4 GPIO_ACTIVE_HIGH>; /* A4 - INT2 */
+		label = "IIS2DLPC";
+	};
+
+	ism330dhcx@6b {
+		compatible = "st,ism330dhcx";
+		reg = <0x6b>;
+		drdy-gpios =  <&arduino_header 11 GPIO_ACTIVE_HIGH>; /* D5 - INT2 */
+		label = "ISM330DHCX";
+	};
+};