drivers: stepper: introduce stepper_drv api to facilitate implementing motion controllers as device drivers

MAINTAINERS.yml

@@ -2400,7 +2400,7 @@ Documentation Infrastructure:
     - include/zephyr/drivers/stepper/
     - include/zephyr/drivers/stepper.h
     - dts/bindings/stepper/
-    - doc/hardware/peripherals/stepper.rst
+    - doc/hardware/peripherals/stepper/
     - samples/drivers/stepper/
     - tests/drivers/build_all/stepper/
     - tests/drivers/stepper/

doc/hardware/peripherals/index.rst

@@ -58,7 +58,7 @@ Peripherals
    sensor/index.rst
    sent.rst
    spi.rst
-   stepper.rst
+   stepper/index.rst
    smbus.rst
    uart.rst
    usbc_vbus.rst

doc/hardware/peripherals/stepper.rst → doc/hardware/peripherals/stepper/index.rst

@@ -3,22 +3,27 @@
 Steppers
 ########
 
-The stepper driver API provides a set of functions for controlling and configuring stepper drivers.
+The stepper driver subsystem consists of two device driver APIs:
 
-Configure Stepper Driver
-========================
+Stepper-DRV API
+***************
+
+The stepper driver API provides a common interface for stepper drivers.
+
+- Configure **micro-stepping resolution** using :c:func:`stepper_drv_set_micro_step_res`
+  and :c:func:`stepper_drv_get_micro_step_res`.
+- **Enable** the stepper driver using :c:func:`stepper_drv_enable`.
+- **Disable** the stepper driver using :c:func:`stepper_drv_disable`.
+- Register an **event callback** using :c:func:`stepper_drv_set_event_cb`.
+
+Stepper API
+***********
+
+The stepper API provides a common interface for stepper controllers.
 
-- Configure **micro-stepping resolution** using :c:func:`stepper_set_micro_step_res`
-  and :c:func:`stepper_get_micro_step_res`.
 - Configure **reference position** in microsteps using :c:func:`stepper_set_reference_position`
   and :c:func:`stepper_get_actual_position`.
 - Set **step interval** in nanoseconds between steps using :c:func:`stepper_set_microstep_interval`
-- **Enable** the stepper driver using :c:func:`stepper_enable`.
-- **Disable** the stepper driver using :c:func:`stepper_disable`.
-
-Control Stepper
-===============
-
 - **Move by** +/- micro-steps also known as **relative movement** using :c:func:`stepper_move_by`.
 - **Move to** a specific position also known as **absolute movement** using :c:func:`stepper_move_to`.
 - Run continuously with a **constant step interval** in a specific direction until
@@ -27,19 +32,27 @@ Control Stepper
 - Check if the stepper is **moving** using :c:func:`stepper_is_moving`.
 - Register an **event callback** using :c:func:`stepper_set_event_callback`.
 
+.. _stepper-device-tree:
+
 Device Tree
-===========
+***********
 
 In the context of stepper controllers  device tree provides the initial hardware
 configuration for stepper drivers on a per device level. Each device must specify
 a device tree binding in Zephyr, and ideally, a set of hardware configuration options
 for things such as current settings, ramp parameters and furthermore. These can then
 be used in a boards devicetree to configure a stepper driver to its initial state.
 
-See examples in:
+Driver Composition Scenarios
+============================
+
+Below are two typical scenarios:
+
+.. toctree::
+   :maxdepth: 1
 
-- :dtcompatible:`zephyr,h-bridge-stepper`
-- :dtcompatible:`adi,tmc50xx`
+   integrated_controller_driver.rst
+   individual_controller_driver.rst
 
 Discord
 =======
@@ -48,9 +61,10 @@ Zephyr has a `stepper discord`_ channel for stepper related discussions, which
 is open to all.
 
 .. _stepper-api-reference:
+.. _stepper-drv-api-reference:
 
 Stepper API Test Suite
-======================
+**********************
 
 The stepper API test suite provides a set of tests that can be used to verify the functionality of
 stepper drivers.
@@ -93,6 +107,10 @@ API Reference
 
 A common set of functions which should be implemented by all stepper drivers.
 
+.. doxygengroup:: stepper_drv_interface
+
+A common set of functions which should be implemented by all stepper controllers.
+
 .. doxygengroup:: stepper_interface
 
 Stepper controller specific APIs

doc/hardware/peripherals/stepper/individual_controller_driver.rst

@@ -0,0 +1,48 @@
+.. _stepper-individual-controller-driver:
+
+Individual Stepper Motion Controller and Driver
+###############################################
+
+A motion control driver implements ``stepper`` API, for instance, :dtcompatible:`zephyr,gpio-step-dir-controller`
+and a hardware driver implements ``stepper_drv`` API, for instance, :dtcompatible:`adi,tmc2209`.
+
+Following is an example of a device tree configuration for a stepper driver with a dedicated stepper motion
+controller:
+
+.. code-block:: dts
+
+    / {
+        aliases {
+            stepper_drv = &tmc2209
+            stepper = &step_dir_motion_control;
+        };
+
+        /* DEVICE_API: stepper_drv api */
+        tmc2209: tmc2209 {
+            compatible = "adi,tmc2209";
+            enable-gpios = <&gpioa 6 GPIO_ACTIVE_HIGH>;
+            msx-gpios = <&gpiob 0 GPIO_ACTIVE_HIGH>, <&gpioa 7 GPIO_ACTIVE_HIGH>;
+        };
+
+        /* DEVICE_API: stepper api */
+        step_dir_motion_control: step_dir_motion_control {
+            compatible = "zephyr,gpio-step-dir-controller";
+            step-gpios = <&gpioa 9 GPIO_ACTIVE_HIGH>;
+            dir-gpios = <&gpioc 7 GPIO_ACTIVE_HIGH>;
+            invert-direction;
+            dual-edge-step;
+            step-width-ns = <1000>;
+        };
+    };
+
+Following the aforementioned configurations, the stepper driver subsystem can be used in the application code
+as follows:
+
+.. code-block:: c
+
+   static const struct device *stepper = DEVICE_DT_GET(DT_ALIAS(stepper));
+   static const struct device *stepper_drv = DEVICE_DT_GET(DT_ALIAS(stepper_drv));
+   ...
+   stepper_move_to(stepper, 200);
+   stepper_stop(stepper);
+   stepper_drv_disable(stepper_drv);

doc/hardware/peripherals/stepper/integrated_controller_driver.rst

@@ -0,0 +1,90 @@
+.. _stepper-integrated-controller-driver:
+
+Integrated Stepper Motion Control and Driver
+############################################
+
+Devices which comprise of both motion controller and a stepper driver in a single IC. These devices
+have to be modelled as multi-functional-device in device tree, implementing both ``stepper`` and
+``stepper_drv`` APIs. An example of such a device is :dtcompatible:`adi,tmc50xx`. ``stepper`` API is
+implemented by :dtcompatible:`adi,tmc50xx-motion-controller` and ``stepper_drv`` API is implemented by
+:dtcompatible:`adi,tmc50xx-stepper-driver`.
+
+.. code-block:: dts
+
+   / {
+       aliases {
+           x_axis_stepper_motor = &tmc50xx_0_motion_controller;
+           y_axis_stepper_motor =  &tmc50xx_1_motion_controller;
+           x_axis_stepper_driver = &tmc50xx_0_stepper_driver;
+           y_axis_stepper_driver = &tmc50xx_1_stepper_driver;
+       };
+   };
+
+   &spi0 {
+       /* SPI bus options here, not shown */
+
+       /* Dual controller/driver for up to two 2-phase bipolar stepper motors */
+       tmc50xx: tmc50xx@0 {
+           compatible = "adi,tmc50xx";
+           reg = <0>;
+           spi-max-frequency = <DT_FREQ_M(8)>; /* Maximum SPI bus frequency */
+
+           poscmp-enable; test-mode; lock-gconf; /* ADI TMC Global configuration flags */
+           clock-frequency = <DT_FREQ_M(16)>; /* Internal/External Clock frequency */
+
+           /* DEVICE_API: stepper_drv api */
+           tmc50xx_0_stepper_driver: tmc50xx_0_stepper_driver {
+               idx = <0>;
+                compatible = "adi,tmc50xx-stepper-driver";
+                micro-step-res = <256>;
+                /* ADI TMC stallguard settings specific to TMC50XX */
+                stallguard2-threshold=<30>;
+            };
+
+           /* DEVICE_API: stepper api */
+           tmc50xx_0_motion_controller: tmc50xx_0_motion_controller {
+               idx = <0>;
+               compatible = "adi,tmc50xx-motion-controller";
+               ...
+               vmax = <900000>;
+               amax = <50000>;
+               ...
+               activate-stallguard2;
+               ...
+            };
+
+           /* DEVICE_API: stepper_drv api */
+           tmc50xx_1_stepper_driver: tmc50xx_1_stepper_driver {
+               idx = <1>;
+                compatible = "adi,tmc50xx-stepper-driver";
+                micro-step-res = <256>;
+                /* ADI TMC stallguard settings specific to TMC50XX */
+                stallguard2-threshold=<30>;
+            };
+
+           /* DEVICE_API: stepper api */
+           tmc50xx_1_motion_controller: tmc50xx_1_motion_controller {
+               idx = <1>;
+               compatible = "adi,tmc50xx-motion-controller";
+               ...
+               vstart = <1000>;
+               ...
+               stallguard-threshold-velocity=<200000>;
+            };
+        };
+   };
+
+Following the aforementioned configurations, the stepper driver subsystem can be used in the application code
+as follows:
+
+.. code-block:: c
+
+   static const struct device *x_stepper = DEVICE_DT_GET(DT_ALIAS(x_axis_stepper_motor));
+   static const struct device *x_stepper_drv = DEVICE_DT_GET(DT_ALIAS(x_axis_stepper_driver));
+   static const struct device *y_stepper = DEVICE_DT_GET(DT_ALIAS(y_axis_stepper_motor));
+   static const struct device *y_stepper_drv = DEVICE_DT_GET(DT_ALIAS(y_axis_stepper_driver));
+   ...
+   stepper_move_to(x_stepper, 200);
+   stepper_stop(x_stepper);
+   stepper_drv_disable(x_stepper_drv);
+   stepper_drv_disable(y_stepper_drv);

drivers/stepper/CMakeLists.txt

@@ -6,16 +6,12 @@ zephyr_syscall_header(${ZEPHYR_BASE}/include/zephyr/drivers/stepper.h)
 # zephyr-keep-sorted-start
 add_subdirectory(adi_tmc)
 add_subdirectory(allegro)
+add_subdirectory(gpio_stepper)
 add_subdirectory(ti)
 # zephyr-keep-sorted-stop
 
-# zephyr-keep-sorted-start
-add_subdirectory(step_dir)
-# zephyr-keep-sorted-stop
-
 zephyr_library()
 zephyr_library_property(ALLOW_EMPTY TRUE)
 
-zephyr_library_sources_ifdef(CONFIG_FAKE_STEPPER fake_stepper_controller.c)
-zephyr_library_sources_ifdef(CONFIG_H_BRIDGE_STEPPER h_bridge_stepper.c)
+zephyr_library_sources_ifdef(CONFIG_FAKE_STEPPER fake_stepper.c)
 zephyr_library_sources_ifdef(CONFIG_STEPPER_SHELL stepper_shell.c)

drivers/stepper/Kconfig

@@ -24,17 +24,13 @@ config STEPPER_SHELL
 	help
 	  Enable stepper shell for testing.
 
-comment "Stepper Driver Common"
-
-rsource "step_dir/Kconfig"
-
 comment "Stepper Drivers"
 
 # zephyr-keep-sorted-start
 rsource "Kconfig.fake"
-rsource "Kconfig.h_bridge"
 rsource "adi_tmc/Kconfig"
 rsource "allegro/Kconfig"
+rsource "gpio_stepper/Kconfig"
 rsource "ti/Kconfig"
 # zephyr-keep-sorted-stop
 

drivers/stepper/Kconfig.fake

@@ -4,8 +4,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 config FAKE_STEPPER
-	bool "Fake stepper driver"
+	bool "Fake stepper"
 	default y
-	depends on DT_HAS_ZEPHYR_FAKE_STEPPER_ENABLED
+	depends on DT_HAS_ZEPHYR_FAKE_STEPPER_DRIVER_ENABLED || DT_HAS_ZEPHYR_FAKE_STEPPER_CONTROLLER_ENABLED
 	help
-	  Enable support for the FFF-based fake stepper driver.
+	  Enable support for the FFF-based fake stepper controller & driver.

drivers/stepper/adi_tmc/CMakeLists.txt

@@ -5,7 +5,8 @@ zephyr_library()
 zephyr_library_property(ALLOW_EMPTY TRUE)
 
 zephyr_library_sources_ifdef(CONFIG_STEPPER_ADI_TMC2209 tmc22xx.c)
-zephyr_library_sources_ifdef(CONFIG_STEPPER_ADI_TMC50XX tmc50xx.c)
-add_subdirectory_ifdef(CONFIG_STEPPER_ADI_TMC51XX tmc51xx)
+add_subdirectory(tmc50xx)
+add_subdirectory(tmc51xx)
 
 add_subdirectory(bus)
+add_subdirectory(common)

drivers/stepper/adi_tmc/Kconfig

@@ -6,5 +6,5 @@ comment "ADI Trinamic Stepper Drivers"
 rsource "bus/Kconfig"
 
 rsource "Kconfig.tmc22xx"
-rsource "Kconfig.tmc50xx"
+rsource "tmc50xx/Kconfig.tmc50xx"
 rsource "tmc51xx/Kconfig.tmc51xx"

drivers/stepper/adi_tmc/Kconfig.tmc22xx

@@ -4,7 +4,6 @@
 config STEPPER_ADI_TMC2209
 	bool "Activate trinamic tmc2209 stepper driver"
 	depends on DT_HAS_ADI_TMC2209_ENABLED
-	select STEP_DIR_STEPPER
 	default y
 	help
 	  Stepper driver for TMC2209.

drivers/stepper/adi_tmc/Kconfig.tmc_rampgen_template

@@ -3,7 +3,6 @@
 
 config STEPPER_ADI_$(module)_RAMPSTAT_POLL_INTERVAL_IN_MSEC
 	int "$(module-str) poll ramp status interval in ms"
-	depends on !$(dt_compat_any_has_prop,$(DT_COMPAT_ADI_$(module)),diag0-gpios)
 	default 100
 	help
 	  When DIAG0 pin is not available, the driver automatically falls back to

drivers/stepper/adi_tmc/common/CMakeLists.txt

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Jilay Sandeep Pandya
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_library_include_directories(include)