drivers: stepper: refactor set_actual_position to set_reference_position

This commit refactos set_actual_position to set_reference_position.
stepper_set_reference_position is more apt in regards to what this func
actually does

Signed-off-by: Jilay Pandya <[email protected]>

Author: jilaypandya

doc/hardware/peripherals/stepper.rst

@@ -10,7 +10,7 @@ Configure Stepper Driver
 
 - 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`
+- Configure **reference position** in microsteps using :c:func:`stepper_set_reference_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`.

doc/releases/migration-guide-4.1.rst

@@ -117,6 +117,7 @@ Stepper
 =======
 
   * Renamed the ``compatible`` from ``zephyr,gpio-steppers`` to :dtcompatible:`zephyr,gpio-stepper`.
+  * Renamed the ``stepper_set_actual_position`` function to :c:func:`stepper_set_reference_position`.
 
 Regulator
 =========

drivers/stepper/adi_tmc/adi_tmc5041_stepper_controller.c

@@ -410,7 +410,7 @@ static int tmc5041_stepper_get_micro_step_res(const struct device *dev,
 	return 0;
 }
 
-static int tmc5041_stepper_set_actual_position(const struct device *dev, const int32_t position)
+static int tmc5041_stepper_set_reference_position(const struct device *dev, const int32_t position)
 {
 	const struct tmc5041_stepper_config *config = dev->config;
 	int err;
@@ -728,7 +728,7 @@ static int tmc5041_stepper_init(const struct device *dev)
 		.set_max_velocity = tmc5041_stepper_set_max_velocity,				\
 		.set_micro_step_res = tmc5041_stepper_set_micro_step_res,			\
 		.get_micro_step_res = tmc5041_stepper_get_micro_step_res,			\
-		.set_actual_position = tmc5041_stepper_set_actual_position,			\
+		.set_reference_position = tmc5041_stepper_set_reference_position,		\
 		.get_actual_position = tmc5041_stepper_get_actual_position,			\
 		.set_target_position = tmc5041_stepper_set_target_position,			\
 		.enable_constant_velocity_mode = tmc5041_stepper_enable_constant_velocity_mode,	\

drivers/stepper/fake_stepper_controller.c

@@ -33,7 +33,7 @@ DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_set_micro_step_res, const struct device
 DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_get_micro_step_res, const struct device *,
 		       enum stepper_micro_step_resolution *);
 
-DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_set_actual_position, const struct device *, int32_t);
+DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_set_reference_position, const struct device *, int32_t);
 
 DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_get_actual_position, const struct device *, int32_t *);
 
@@ -65,7 +65,7 @@ static int fake_stepper_get_micro_step_res_delegate(const struct device *dev,
 	return 0;
 }
 
-static int fake_stepper_set_actual_position_delegate(const struct device *dev, const int32_t pos)
+static int fake_stepper_set_reference_position_delegate(const struct device *dev, const int32_t pos)
 {
 	struct fake_stepper_data *data = dev->data;
 
@@ -95,16 +95,16 @@ static void fake_stepper_reset_rule_before(const struct ztest_unit_test *test, v
 	RESET_FAKE(fake_stepper_set_max_velocity);
 	RESET_FAKE(fake_stepper_set_micro_step_res);
 	RESET_FAKE(fake_stepper_get_micro_step_res);
-	RESET_FAKE(fake_stepper_set_actual_position);
+	RESET_FAKE(fake_stepper_set_reference_position);
 	RESET_FAKE(fake_stepper_get_actual_position);
 	RESET_FAKE(fake_stepper_set_target_position);
 	RESET_FAKE(fake_stepper_enable_constant_velocity_mode);
 
 	/* Install custom fakes for the setter and getter functions */
 	fake_stepper_set_micro_step_res_fake.custom_fake = fake_stepper_set_micro_step_res_delegate;
 	fake_stepper_get_micro_step_res_fake.custom_fake = fake_stepper_get_micro_step_res_delegate;
-	fake_stepper_set_actual_position_fake.custom_fake =
-		fake_stepper_set_actual_position_delegate;
+	fake_stepper_set_reference_position_fake.custom_fake =
+		fake_stepper_set_reference_position_delegate;
 	fake_stepper_get_actual_position_fake.custom_fake =
 		fake_stepper_get_actual_position_delegate;
 }
@@ -116,8 +116,8 @@ static int fake_stepper_init(const struct device *dev)
 {
 	fake_stepper_set_micro_step_res_fake.custom_fake = fake_stepper_set_micro_step_res_delegate;
 	fake_stepper_get_micro_step_res_fake.custom_fake = fake_stepper_get_micro_step_res_delegate;
-	fake_stepper_set_actual_position_fake.custom_fake =
-		fake_stepper_set_actual_position_delegate;
+	fake_stepper_set_reference_position_fake.custom_fake =
+		fake_stepper_set_reference_position_delegate;
 	fake_stepper_get_actual_position_fake.custom_fake =
 		fake_stepper_get_actual_position_delegate;
 
@@ -131,7 +131,7 @@ static const struct stepper_driver_api fake_stepper_driver_api = {
 	.set_max_velocity = fake_stepper_set_max_velocity,
 	.set_micro_step_res = fake_stepper_set_micro_step_res,
 	.get_micro_step_res = fake_stepper_get_micro_step_res,
-	.set_actual_position = fake_stepper_set_actual_position,
+	.set_reference_position = fake_stepper_set_reference_position,
 	.get_actual_position = fake_stepper_get_actual_position,
 	.set_target_position = fake_stepper_set_target_position,
 	.enable_constant_velocity_mode = fake_stepper_enable_constant_velocity_mode,

drivers/stepper/gpio_stepper_controller.c

@@ -194,7 +194,7 @@ static int gpio_stepper_move(const struct device *dev, int32_t micro_steps)
 	return 0;
 }
 
-static int gpio_stepper_set_actual_position(const struct device *dev, int32_t position)
+static int gpio_stepper_set_reference_position(const struct device *dev, int32_t position)
 {
 	struct gpio_stepper_data *data = dev->data;
 
@@ -356,7 +356,7 @@ static const struct stepper_driver_api gpio_stepper_api = {
 	.enable = gpio_stepper_enable,
 	.move = gpio_stepper_move,
 	.is_moving = gpio_stepper_is_moving,
-	.set_actual_position = gpio_stepper_set_actual_position,
+	.set_reference_position = gpio_stepper_set_reference_position,
 	.get_actual_position = gpio_stepper_get_actual_position,
 	.set_target_position = gpio_stepper_set_target_position,
 	.set_max_velocity = gpio_stepper_set_max_velocity,

drivers/stepper/stepper_shell.c

@@ -294,7 +294,7 @@ static int cmd_stepper_get_micro_step_res(const struct shell *sh, size_t argc, c
 	return err;
 }
 
-static int cmd_stepper_set_actual_position(const struct shell *sh, size_t argc, char **argv)
+static int cmd_stepper_set_reference_position(const struct shell *sh, size_t argc, char **argv)
 {
 	const struct device *dev;
 	int err = 0;
@@ -309,7 +309,7 @@ static int cmd_stepper_set_actual_position(const struct shell *sh, size_t argc,
 		return err;
 	}
 
-	err = stepper_set_actual_position(dev, position);
+	err = stepper_set_reference_position(dev, position);
 	if (err) {
 		shell_error(sh, "Error: %d", err);
 	}
@@ -462,8 +462,8 @@ SHELL_STATIC_SUBCMD_SET_CREATE(
 		      "<device> <resolution>", cmd_stepper_set_micro_step_res, 3, 0),
 	SHELL_CMD_ARG(get_micro_step_res, &dsub_pos_stepper_motor_name, "<device>",
 		      cmd_stepper_get_micro_step_res, 2, 0),
-	SHELL_CMD_ARG(set_actual_position, &dsub_pos_stepper_motor_name, "<device> <position>",
-		      cmd_stepper_set_actual_position, 3, 0),
+	SHELL_CMD_ARG(set_reference_position, &dsub_pos_stepper_motor_name, "<device> <position>",
+		      cmd_stepper_set_reference_position, 3, 0),
 	SHELL_CMD_ARG(get_actual_position, &dsub_pos_stepper_motor_name, "<device>",
 		      cmd_stepper_get_actual_position, 2, 0),
 	SHELL_CMD_ARG(set_target_position, &dsub_pos_stepper_motor_name, "<device> <micro_steps>",

include/zephyr/drivers/stepper.h

@@ -7,6 +7,7 @@
 
 /*
  * SPDX-FileCopyrightText: Copyright (c) 2024 Carl Zeiss Meditec AG
+ * SPDX-FileCopyrightText: Copyright (c) 2024 Jilay Sandeep Pandya
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -135,11 +136,11 @@ typedef int (*stepper_set_micro_step_res_t)(const struct device *dev,
 typedef int (*stepper_get_micro_step_res_t)(const struct device *dev,
 					    enum stepper_micro_step_resolution *resolution);
 /**
- * @brief Set the actual a.k.a reference position of the stepper
+ * @brief Set the reference position of the stepper
  *
  * @see stepper_set_actual_position() for details.
  */
-typedef int (*stepper_set_actual_position_t)(const struct device *dev, const int32_t value);
+typedef int (*stepper_set_reference_position_t)(const struct device *dev, const int32_t value);
 
 /**
  * @brief Get the actual a.k.a reference position of the stepper
@@ -194,7 +195,7 @@ __subsystem struct stepper_driver_api {
 	stepper_set_max_velocity_t set_max_velocity;
 	stepper_set_micro_step_res_t set_micro_step_res;
 	stepper_get_micro_step_res_t get_micro_step_res;
-	stepper_set_actual_position_t set_actual_position;
+	stepper_set_reference_position_t set_reference_position;
 	stepper_get_actual_position_t get_actual_position;
 	stepper_set_target_position_t set_target_position;
 	stepper_is_moving_t is_moving;
@@ -318,7 +319,7 @@ static inline int z_impl_stepper_get_micro_step_res(const struct device *dev,
 }
 
 /**
- * @brief Set the actual a.k.a reference position of the stepper
+ * @brief Set the reference position of the stepper
  *
  * @param dev Pointer to the stepper motor controller instance.
  * @param value The reference position to set in micro-steps.
@@ -327,16 +328,17 @@ static inline int z_impl_stepper_get_micro_step_res(const struct device *dev,
  * @retval -ENOSYS If not implemented by device driver
  * @retval 0 Success
  */
-__syscall int stepper_set_actual_position(const struct device *dev, int32_t value);
+__syscall int stepper_set_reference_position(const struct device *dev, int32_t value);
 
-static inline int z_impl_stepper_set_actual_position(const struct device *dev, const int32_t value)
+static inline int z_impl_stepper_set_reference_position(const struct device *dev,
+							const int32_t value)
 {
 	const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api;
 
-	if (api->set_actual_position == NULL) {
+	if (api->set_reference_position == NULL) {
 		return -ENOSYS;
 	}
-	return api->set_actual_position(dev, value);
+	return api->set_reference_position(dev, value);
 }
 
 /**

include/zephyr/drivers/stepper/stepper_fake.h

@@ -26,7 +26,7 @@ DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_set_micro_step_res, const struct devic
 DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_get_micro_step_res, const struct device *,
 			enum stepper_micro_step_resolution *);
 
-DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_set_actual_position, const struct device *, int32_t);
+DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_set_reference_position, const struct device *, int32_t);
 
 DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_get_actual_position, const struct device *, int32_t *);
 

tests/drivers/stepper/shell/src/main.c

@@ -99,13 +99,13 @@ ZTEST(stepper_shell, test_stepper_get_micro_step_res)
 	ASSERT_STEPPER_FUNC_CALLED(fake_stepper_get_micro_step_res_fake, err);
 }
 
-ZTEST(stepper_shell, test_stepper_set_actual_position)
+ZTEST(stepper_shell, test_stepper_set_reference_position)
 {
 	const struct shell *sh = shell_backend_dummy_get_ptr();
-	int err = shell_execute_cmd(sh, "stepper set_actual_position " FAKE_STEPPER_NAME " 100");
+	int err = shell_execute_cmd(sh, "stepper set_reference_position " FAKE_STEPPER_NAME " 100");
 
-	ASSERT_STEPPER_FUNC_CALLED(fake_stepper_set_actual_position_fake, err);
-	zassert_equal(fake_stepper_set_actual_position_fake.arg1_val, 100,
+	ASSERT_STEPPER_FUNC_CALLED(fake_stepper_set_reference_position_fake, err);
+	zassert_equal(fake_stepper_set_reference_position_fake.arg1_val, 100,
 		      "wrong actual position value");
 }
 

tests/drivers/stepper/stepper_api/src/main.c

@@ -56,7 +56,7 @@ static void *stepper_setup(void)
 static void stepper_before(void *f)
 {
 	struct stepper_fixture *fixture = f;
-	(void)stepper_set_actual_position(fixture->dev, 0);
+	(void)stepper_set_reference_position(fixture->dev, 0);
 	k_poll_signal_reset(&stepper_signal);
 }
 
@@ -73,7 +73,7 @@ ZTEST_F(stepper, test_micro_step_res)
 ZTEST_F(stepper, test_actual_position)
 {
 	int32_t pos = 100u;
-	(void)stepper_set_actual_position(fixture->dev, pos);
+	(void)stepper_set_reference_position(fixture->dev, pos);
 	(void)stepper_get_actual_position(fixture->dev, &pos);
 	zassert_equal(pos, 100u, "Actual position not set correctly");
 }