From 7b8e8c95baea9eb180cb7fedc63bb66e63bd32f0 Mon Sep 17 00:00:00 2001 From: ligr Date: Tue, 23 Sep 2025 11:16:12 +0800 Subject: [PATCH] [components/lwp]add doxygen comment for lwp_dbg.c. --- components/lwp/lwp_dbg.c | 100 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/components/lwp/lwp_dbg.c b/components/lwp/lwp_dbg.c index c630f3291e..6fdac2cbb6 100644 --- a/components/lwp/lwp_dbg.c +++ b/components/lwp/lwp_dbg.c @@ -1,7 +1,21 @@ +/* + * Copyright (c) 2006-2025 RT-Thread Development Team + * + * SPDX-License-Identifier: Apache-2.0 + * + * Change Logs: + * Date Author Notes + * 2023-07-11 RT-Thread first version + */ #include #include #include +/** + * @brief Check if the current thread is in debug state. + * + * @return int Returns 1 if the thread is in debug state, 0 otherwise. + */ int dbg_thread_in_debug(void) { int ret = 0; @@ -17,12 +31,30 @@ int dbg_thread_in_debug(void) struct dbg_ops_t *rt_dbg_ops = RT_NULL; RTM_EXPORT(rt_dbg_ops); +/** + * @brief Register debugger operations. + * + * @param dbg_ops Pointer to debugger operations structure. + */ void dbg_register(struct dbg_ops_t *dbg_ops) { rt_dbg_ops = dbg_ops; } RTM_EXPORT(dbg_register); +/** + * @brief Debug command handler function + * + * @param[in] argc Number of command arguments + * @param[in] argv Array of command argument strings + * + * @return int Returns the result from the debug operations handler if available, + * otherwise returns -1 to indicate failure + * + * @note This function serves as a wrapper for debug operations, delegating to the registered + * debug operations handler if available. If no debug operations are registered, + * it prints an error message. + */ static int dbg(int argc, char **argv) { int ret = -1; @@ -39,6 +71,16 @@ static int dbg(int argc, char **argv) } MSH_CMD_EXPORT(dbg, dbg); +/** + * @brief Get the current instruction value from debug operations + * + * @return uint32_t Returns the current instruction value if debug operations are available, + * otherwise returns 0 + * + * @note This function retrieves the current instruction value by calling the registered + * debug operations handler if available. If no debug operations are registered, + * it returns 0. + */ uint32_t dbg_get_ins(void) { uint32_t ins = 0; @@ -50,6 +92,12 @@ uint32_t dbg_get_ins(void) return ins; } +/** + * @brief Activates single-step debugging mode if debug operations are registered + * + * @note This function checks if debug operations are registered (rt_dbg_ops) and if so, + * calls the architecture-specific single-step activation function. + */ void dbg_activate_step(void) { if (rt_dbg_ops) @@ -58,6 +106,12 @@ void dbg_activate_step(void) } } +/** + * @brief Deactivates single-step debugging mode if debug operations are registered + * + * @note This function checks if debug operations are registered (rt_dbg_ops) and if so, + * calls the architecture-specific single-step deactivation function. + */ void dbg_deactivate_step(void) { if (rt_dbg_ops) @@ -66,6 +120,18 @@ void dbg_deactivate_step(void) } } +/** + * @brief Checks for debug events and processes them if debug operations are registered + * + * @param[in] regs Pointer to the hardware exception stack containing register values + * @param[in] esr Exception Syndrome Register value + * + * @return int Returns the result from the debug event check (0 if no debug operations registered) + * + * @note This function checks if debug operations are registered (rt_dbg_ops) and if so, + * calls the debug event checking function with the provided registers and exception status. + * If no debug operations are registered, it returns 0. + */ int dbg_check_event(struct rt_hw_exp_stack *regs, unsigned long esr) { int ret = 0; @@ -77,6 +143,15 @@ int dbg_check_event(struct rt_hw_exp_stack *regs, unsigned long esr) return ret; } +/** + * @brief Gets the GDB server communication channel if debug operations are registered + * + * @return rt_channel_t Returns the GDB server channel (RT_NULL if no debug operations registered) + * + * @note This function checks if debug operations are registered (rt_dbg_ops) and if so, + * retrieves the GDB server communication channel from the registered operations. + * If no debug operations are registered, it returns RT_NULL. + */ rt_channel_t gdb_server_channel(void) { rt_channel_t ret = RT_NULL; @@ -88,6 +163,15 @@ rt_channel_t gdb_server_channel(void) return ret; } +/** + * @brief Gets the current step type from debug operations + * + * @return int The current step type (0 if no debug operations are registered) + * + * @note This function checks if debug operations are registered (rt_dbg_ops) and if so, + * retrieves the current step type from the registered debug operations. + * If no debug operations are registered, it returns 0. + */ int dbg_step_type(void) { int ret = 0; @@ -99,6 +183,14 @@ int dbg_step_type(void) return ret; } +/** + * @brief Handles debug attach request + * + * @param[in] pc Pointer to the program counter value + * + * @note This function checks if debug operations are registered and calls + * the debug attach request handler if available. + */ void dbg_attach_req(void *pc) { if (rt_dbg_ops) @@ -107,6 +199,14 @@ void dbg_attach_req(void *pc) } } +/** + * @brief Checks if debug suspend is requested + * + * @return int Returns the suspend status (0 if no debug operations are registered) + * + * @note This function checks if debug operations are registered and calls + * the debug suspend check handler if available. + */ int dbg_check_suspend(void) { int ret = 0;