RFC: Breaking API Change: Shell: Allow passing an opaque user data pointer to the bypass callback function

[pdgendt]

Problem Description

The Shell subsystem has an API to temporarily bypass the incoming data to a callback function. This bypass callback function does not have a way to set a user context alongside the callback.

Proposed Change (Summary)

The proposed change is to alter the shell_set_bypass API function to also pas a user data pointer. This user data pointer is also an argument for the bypass callback function.

This was already applied in #97187 but did not go through the breaking API change steps, and is reverted in #97457

Proposed Change (Detailed)

The proposed diff to the API

diff --git a/include/zephyr/shell/shell.h b/include/zephyr/shell/shell.h
index ba275c5393c..0a070d35bfc 100644
--- a/include/zephyr/shell/shell.h
+++ b/include/zephyr/shell/shell.h
@@ -789,7 +789,8 @@ typedef void (*shell_uninit_cb_t)(const struct shell *sh, int res);
  */
 typedef void (*shell_bypass_cb_t)(const struct shell *sh,
                                  uint8_t *data,
-                                 size_t len);
+                                 size_t len,
+                                 void *user_data);

 struct shell_transport;

@@ -990,6 +991,9 @@ struct shell_ctx {
        /** When bypass is set, all incoming data is passed to the callback. */
        shell_bypass_cb_t bypass;

+       /** When bypass is set, this user data pointer is passed to the callback. */
+       void *bypass_user_data;
+
        /*!< Logging level for a backend. */
        uint32_t log_level;

@@ -1364,8 +1368,9 @@ int shell_set_root_cmd(const char *cmd);
  *
  * @param[in] sh       Pointer to the shell instance.
  * @param[in] bypass   Bypass callback or null to disable.
+ * @param[in] user_data        Bypass callback user data.
  */
-void shell_set_bypass(const struct shell *sh, shell_bypass_cb_t bypass);
+void shell_set_bypass(const struct shell *sh, shell_bypass_cb_t bypass, void *user_data);

 /** @brief Get shell readiness to execute commands.
  *

See #97187

Dependencies

No response

Concerns and Unresolved Questions

No response

Alternatives Considered

An alternative is to not break the API and put the user data into the shell context directly, without the coupling to the bypass function.

See #97467

[carlescufi]

Architecture WG meeting:

• No objections to this breaking change