doc: stepper: update stepper documentation

This commit adds documentation about stepper api along
with some minor cleanups

Signed-off-by: Jilay Pandya <jilay.pandya@zeiss.com>

doc/hardware/peripherals/stepper.rst

@@ -1,24 +1,65 @@
 .. _stepper_api:
 
-Stepper API
+Steppers
-###########
+########
 
-Overview
+The stepper driver API provides a set of functions for controlling and configuring stepper drivers.
-********
 
-The Stepper API provides a set of functions for controlling and configuring stepper motors.
+Configure Stepper Driver
-It supports a variety of operations, including enabling/disabling the controller, setting the
+========================
-target position of the motor and thereby setting the motor in motion, setting/getting the actual
-position of the motor and so on.
 
-Configuration Options
+- Configure **micro-stepping resolution** using :c:func:`stepper_set_micro_step_res`
-*********************
+  and :c:func:`stepper_get_micro_step_res`.
+- Configure **actual position a.k.a step count** in microsteps using :c:func:`stepper_set_actual_position`
+  and :c:func:`stepper_get_actual_position`.
+- Set **max velocity** in micro-steps per second using :c:func:`stepper_set_max_velocity`
+- **Enable** the stepper driver using :c:func:`stepper_enable`.
 
-Related configuration options:
+Control Stepper
+===============
 
-* :kconfig:option:`CONFIG_STEPPER_INIT_PRIORITY`
+- **Move by** +/- micro-steps also known as **relative movement** using :c:func:`stepper_move`.
+- **Move to** a specific position also known as **absolute movement**
+  using :c:func:`stepper_set_target_position`.
+- Run continuously with a **constant velocity** in a specific direction until
+  a stop is detected using :c:func:`stepper_enable_constant_velocity_mode`.
+- Check if the stepper is **moving** using :c:func:`stepper_is_moving`.
+
+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:
+
+- :dtcompatible:`adi,tmc5041`
+
+Discord
+=======
+
+Zephyr has a `stepper discord`_ channel for stepper related discussions, which
+is open to all.
+
+.. _stepper-api-reference:
 
 API Reference
 *************
 
+A common set of functions which should be implemented by all stepper drivers.
+
 .. doxygengroup:: stepper_interface
+
+Stepper controller specific APIs
+********************************
+
+Trinamic
+========
+
+.. doxygengroup:: trinamic_stepper_interface
+
+.. _stepper discord:
+   https://discord.com/channels/720317445772017664/1278263869982375946

dts/bindings/stepper/adi/adi,tmc5041.yaml

@@ -1,7 +1,60 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024 Carl Zeiss Meditec AG
 # SPDX-License-Identifier: Apache-2.0
 
-description: Analog Devices TMC5041 Stepper Motor Controller
+description: |
+  Analog Devices TMC5041 Stepper Motor Controller
+
+  Example:
+
+    #include <zephyr/dt-bindings/stepper/adi/tmc5041_reg.h>
+
+    &spi0 {
+        /* SPI bus options here, not shown */
+
+        /* Dual controller/driver for up to two 2-phase bipolar stepper motors */
+        tmc5041: tmc5041@0 {
+            compatible = "adi,tmc5041";
+            reg = <0>;
+            spi-max-frequency = <DT_FREQ_M(24)>; /* Maximum SPI bus frequency */
+
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            poscmp_enable; test_mode; lock_gconf; /* ADI TMC Global configuration flags */
+            clock-frequency = <DT_FREQ_M(16)>; /* Internal/External Clock frequency */
+
+            motor: motor@0 {
+                status = "okay";
+                reg = <0>;
+
+                /* common stepper controller settings */
+                invert-direction;
+                micro-step-res = <256>;
+
+                /* ADI TMC stallguard settings specific to TMC5041 */
+                activate-stallguard2;
+                stallguard-velocity-check-interval-ms=<100>;
+                stallguard2-threshold=<9>;
+                stallguard-threshold-velocity=<500000>;
+
+                /* ADI TMC ramp generator as well as current settings */
+                vstart = <10>;
+                a1 = <20>;
+                v1 = <30>;
+                d1 = <40>;
+                vmax = <50>;
+                amax = <60>;
+                dmax = <70>;
+                tzerowait = <80>;
+                vhigh = <90>;
+                vcoolthrs = <100>;
+                ihold = <1>;
+                irun = <2>;
+                iholddelay = <3>;
+            };
+        };
+    };
+
 
 compatible: "adi,tmc5041"
 

include/zephyr/drivers/stepper.h

@@ -14,8 +14,8 @@
 #define ZEPHYR_INCLUDE_DRIVERS_STEPPER_H_
 
 /**
- * @brief Stepper Motor Controller Interface
+ * @brief Stepper Controller Interface
- * @defgroup stepper_interface Stepper Motor Controller Interface
+ * @defgroup stepper_interface Stepper Controller Interface
  * @ingroup io_interfaces
  * @{
  */

include/zephyr/drivers/stepper/stepper_trinamic.h

@@ -58,6 +58,7 @@ extern "C" {
 #define TMC_RAMP_IHOLDDELAY_MAX GENMASK(3, 0)
 #define TMC_RAMP_IHOLDDELAY_MIN 0
 #define TMC_RAMP_VACTUAL_SHIFT  22
+
 /**
  * @brief Trinamic Stepper Ramp Generator data
  */