drivers: Add mdio API

This commit adds support for MDIO bus. The bus is used by Ethernet
MACs to communicate with PHYs.

Signed-off-by: Arvin Farahmand <arvinf@ip-logix.com>

CODEOWNERS

@@ -222,6 +222,7 @@
 /drivers/ethernet/*stm32*                 @Nukersson @lochej
 /drivers/ethernet/*w5500*                 @parthitce
 /drivers/ethernet/*xlnx_gem*              @ibirnbaum
+/drivers/mdio/                            @rlubos @tbursztyka @arvinf
 /drivers/flash/                           @nashif @nvlsianpu
 /drivers/flash/*b91*                      @yurvyn
 /drivers/flash/*nrf*                      @nvlsianpu

doc/reference/peripherals/index.rst

@@ -32,6 +32,7 @@ Peripherals
    sensor.rst
    spi.rst
    uart.rst
+   mdio.rst
    watchdog.rst
    video.rst
    espi.rst

doc/reference/peripherals/mdio.rst

@@ -0,0 +1,20 @@
+.. _mdio_api:
+
+MDIO
+####
+
+Overview
+********
+
+MDIO is a bus that is commonly used to communicate with ethernet PHY devices.
+Many ethernet MAC controllers also provide hardware to communicate over MDIO
+bus with a peripheral device.
+
+This API is intended to be used primarily by PHY drivers but can also be
+used by user firmware.
+
+API Reference
+*************
+
+.. doxygengroup:: mdio_interface
+   :project: Zephyr

drivers/CMakeLists.txt

@@ -20,6 +20,7 @@ add_subdirectory_ifdef(CONFIG_GPIO gpio)
 add_subdirectory_ifdef(CONFIG_EC_HOST_CMD_PERIPH ec_host_cmd_periph)
 add_subdirectory_ifdef(CONFIG_I2C i2c)
 add_subdirectory_ifdef(CONFIG_I2S i2s)
+add_subdirectory_ifdef(CONFIG_MDIO mdio)
 add_subdirectory_ifdef(CONFIG_IEEE802154 ieee802154)
 add_subdirectory_ifdef(CONFIG_IPM ipm)
 add_subdirectory_ifdef(CONFIG_LED led)

drivers/Kconfig

@@ -19,6 +19,8 @@ source "drivers/ec_host_cmd_periph/Kconfig"
 
 source "drivers/ethernet/Kconfig"
 
+source "drivers/mdio/Kconfig"
+
 source "drivers/net/Kconfig"
 
 source "drivers/serial/Kconfig"

drivers/mdio/CMakeLists.txt

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_library()

drivers/mdio/Kconfig

@@ -0,0 +1,30 @@
+# MDIO configuration options
+
+# Copyright (c) 2021 IP-Logix Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+#
+# MDIO options
+#
+menuconfig MDIO
+	bool "MDIO Drivers"
+	help
+	  Enable MDIO Driver Configuration
+
+if MDIO
+
+# Include these first so that any properties (e.g. defaults) below can be
+# overridden (by defining symbols in multiple locations)
+
+config MDIO_INIT_PRIORITY
+	int "Init priority"
+	default 60
+	help
+	  MDIO device driver initialization priority.
+
+
+module = MDIO
+module-str = mdio
+source "subsys/logging/Kconfig.template.log_config"
+
+endif # MDIO

dts/bindings/mdio/mdio-controller.yaml

@@ -0,0 +1,27 @@
+# Copyright (c) 2021 IP-Logix Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# Common fields for MDIO controllers
+
+include: base.yaml
+
+bus: mdio
+
+properties:
+    label:
+      required: true
+    protocol:
+      required: false
+      type: string
+      description: |
+        MDIO bus framing protocol to use for communication. Most devices
+        support clause 22.
+
+        - clause 22: IEEE802.3 clause 22 frame format
+        - clause 45: IEEE802.3 clause 45 frame format
+        - micrel SMI: Micrel Serial Management Interface frame format
+      enum:
+        - "clause 22"
+        - "clause 45"
+        - "micrel SMI"
+      default: "clause 22"

include/drivers/mdio.h

@@ -0,0 +1,158 @@
+/**
+ * @file
+ *
+ * @brief Public APIs for MDIO drivers.
+ */
+
+/*
+ * Copyright (c) 2021 IP-Logix Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#ifndef ZEPHYR_INCLUDE_DRIVERS_MDIO_H_
+#define ZEPHYR_INCLUDE_DRIVERS_MDIO_H_
+
+/**
+ * @brief MDIO Interface
+ * @defgroup mdio_interface MDIO Interface
+ * @ingroup io_interfaces
+ * @{
+ */
+#include <zephyr/types.h>
+#include <device.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @cond INTERNAL_HIDDEN
+ *
+ * These are for internal use only, so skip these in
+ * public documentation.
+ */
+
+/** Order of items in this enum must match the `protocol` dts binding */
+enum MDIO_PROTOCOL {
+	CLAUSE_22	= 0,
+	CLAUSE_45	= 1,
+	MICREL_SMI	= 2,
+};
+
+__subsystem struct mdio_driver_api {
+	/** Enable the MDIO bus device */
+	void (*bus_enable)(const struct device *dev);
+
+	/** Disable the MDIO bus device */
+	void (*bus_disable)(const struct device *dev);
+
+	/** Read data from MDIO bus */
+	int (*read)(const struct device *dev, uint8_t prtad, uint8_t devad,
+		    uint16_t *data);
+
+	/** Write data to MDIO bus */
+	int (*write)(const struct device *dev, uint8_t prtad, uint8_t devad,
+		     uint16_t data);
+};
+/**
+ * @endcond
+ */
+
+/**
+ * @brief      Enable MDIO bus
+ *
+ * @param[in]  dev   Pointer to the device structure for the controller
+ *
+ */
+__syscall void mdio_bus_enable(const struct device *dev);
+
+static inline void z_impl_mdio_bus_enable(const struct device *dev)
+{
+	const struct mdio_driver_api *api =
+		(const struct mdio_driver_api *)dev->api;
+
+	return api->bus_enable(dev);
+}
+
+/**
+ * @brief      Disable MDIO bus and tri-state drivers
+ *
+ * @param[in]  dev   Pointer to the device structure for the controller
+ *
+ */
+__syscall void mdio_bus_disable(const struct device *dev);
+
+static inline void z_impl_mdio_bus_disable(const struct device *dev)
+{
+	const struct mdio_driver_api *api =
+		(const struct mdio_driver_api *)dev->api;
+
+	return api->bus_disable(dev);
+}
+
+/**
+ * @brief      Read from MDIO Bus
+ *
+ * This routine provides a generic interface to perform a read on the
+ * MDIO bus.
+ *
+ * @param[in]  dev         Pointer to the device structure for the controller
+ * @param[in]  prtad       Port address
+ * @param[in]  devad       Device address
+ * @param      data        Pointer to receive read data
+ *
+ * @retval 0 If successful.
+ * @retval -EIO General input / output error.
+ * @retval -ETIMEDOUT If transaction timedout on the bus
+ */
+__syscall int mdio_read(const struct device *dev, uint8_t prtad, uint8_t devad,
+			uint16_t *data);
+
+static inline int z_impl_mdio_read(const struct device *dev, uint8_t prtad,
+				   uint8_t devad, uint16_t *data)
+{
+	const struct mdio_driver_api *api =
+		(const struct mdio_driver_api *)dev->api;
+
+	return api->read(dev, prtad, devad, data);
+}
+
+
+/**
+ * @brief      Write to MDIO bus
+ *
+ * This routine provides a generic interface to perform a write on the
+ * MDIO bus.
+ *
+ * @param[in]  dev         Pointer to the device structure for the controller
+ * @param[in]  prtad       Port address
+ * @param[in]  devad       Device address
+ * @param[in]  data        Data to write
+ *
+ * @retval 0 If successful.
+ * @retval -EIO General input / output error.
+ * @retval -ETIMEDOUT If transaction timedout on the bus
+ */
+__syscall int mdio_write(const struct device *dev, uint8_t prtad, uint8_t devad,
+			 uint16_t data);
+
+static inline int z_impl_mdio_write(const struct device *dev, uint8_t prtad,
+				    uint8_t devad, uint16_t data)
+{
+	const struct mdio_driver_api *api =
+		(const struct mdio_driver_api *)dev->api;
+
+	return api->write(dev, prtad, devad, data);
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
+
+#include <syscalls/mdio.h>
+
+#endif /* ZEPHYR_INCLUDE_DRIVERS_MDIO_H_ */